Tickets can be shared between Zendesk accounts. To enable ticket sharing, a sharing agreement must be sent by one account and accepted by the other account. Sharing agreements work as follows:

  • Any Zendesk account can invite another account to establish a sharing agreement.
  • The initiating account (the sender) sets the terms of the sharing agreement, which the receiving account can accept or not.
  • Sharing agreements are one way. Once the receiver accepts the agreement, the sender may share tickets with the receiver. If the receiver wants to share tickets with the sender, they must create and send a sharing agreement to the other account.

To learn more, see Sharing tickets with other Zendesk accounts in Zendesk help.

JSON format

Sharing Agreements are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
created_at string true false The time the record was created
id integer true false Automatically assigned upon creation
name string false false Name of this sharing agreement
partner_name string false false Can be one of the following: "jira", null
remote_subdomain string false false Subdomain of the remote account or null if not associated with an account
status string false false Can be one of the following: "accepted", "declined", "pending", "inactive", "failed", "ssl_error", "configuration_error"
type string false false Can be one of the following: "inbound", "outbound"
updated_at string true false The time the record was updated
url string true false URL of the sharing agreement record

Example

{  "created_at": "2012-02-20T22:55:29Z",  "id": 88335,  "name": "Ticket Sharing",  "partner_name": "jira",  "status": "accepted",  "type": "inbound",  "updated_at": "2013-02-20T22:55:29Z",  "url": "https://company.zendesk.com/api/v2/agreements/88335.json"}

List Sharing Agreements

  • GET /api/v2/sharing_agreements

Allowed For

  • Agents

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/sharing_agreements.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/sharing_agreements"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/sharing_agreements")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/sharing_agreements',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/sharing_agreements"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/sharing_agreements")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "sharing_agreements": [    {      "created_at": "2012-02-20T22:55:29Z",      "id": 1,      "name": "Foo @ Zendesk",      "partner_name": "jira",      "status": "accepted",      "type": "inbound",      "updated_at": "2013-02-20T22:55:29Z",      "url": "https://company.zendesk.com/api/v2/agreements/1.json"    }  ]}

Show a Sharing Agreement

  • GET /api/v2/sharing_agreements/{sharing_agreement_id}

Returns a sharing agreement for your account.

Allowed For

  • Agents

Parameters

Name Type In Required Description
sharing_agreement_id integer Path true The ID of the sharing agreement

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/sharing_agreements/{sharing_agreement_id}.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/sharing_agreements/1"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/sharing_agreements/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/sharing_agreements/1',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/sharing_agreements/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/sharing_agreements/1")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "sharing_agreement": {    "created_at": "2012-02-20T22:55:29Z",    "id": 1,    "name": "Foo @ Zendesk",    "partner_name": null,    "remote_subdomain": "foo",    "status": "accepted",    "type": "inbound",    "updated_at": "2013-02-20T22:55:29Z",    "url": "https://company.zendesk.com/api/v2/agreements/1.json"  }}

Create Sharing Agreement

  • POST /api/v2/sharing_agreements

Allowed For

  • Admins

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/sharing_agreements.json \  -H "Content-Type: application/json" -X POST \  -d '{"sharing_agreement": {"remote_subdomain": "Foo"}}' \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/sharing_agreements"	method := "POST"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/sharing_agreements")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://example.zendesk.com/api/v2/sharing_agreements',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/sharing_agreements"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/sharing_agreements")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created
// Status 201 Created
{  "sharing_agreement": {    "created_at": "2012-02-20T22:55:29Z",    "id": 1,    "name": "Foo @ Zendesk",    "partner_name": null,    "remote_subdomain": "foo",    "status": "accepted",    "type": "inbound",    "updated_at": "2013-02-20T22:55:29Z",    "url": "https://company.zendesk.com/api/v2/agreements/1.json"  }}

Update a Sharing Agreement

  • PUT /api/v2/sharing_agreements/{sharing_agreement_id}

Returns an updated sharing agreement. Only status is allowed to be updated.

Allowed For

  • Admins

Parameters

Name Type In Required Description
sharing_agreement_id integer Path true The ID of the sharing agreement

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/sharing_agreements/{sharing_agreement_id}.json \  -H "Content-Type: application/json" -X PUT \  -d '{"sharing_agreement": {"status": "accepted"}}' \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/sharing_agreements/1"	method := "PUT"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/sharing_agreements/1")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'PUT',  url: 'https://example.zendesk.com/api/v2/sharing_agreements/1',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/sharing_agreements/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/sharing_agreements/1")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "sharing_agreement": {    "created_at": "2012-02-20T22:55:29Z",    "id": 1,    "name": "Foo @ Zendesk",    "partner_name": null,    "remote_subdomain": "foo",    "status": "accepted",    "type": "inbound",    "updated_at": "2013-02-20T22:55:29Z",    "url": "https://company.zendesk.com/api/v2/agreements/1.json"  }}

Delete a Sharing Agreement

  • DELETE /api/v2/sharing_agreements/{sharing_agreement_id}

Deletes a sharing agreement.

Allowed For

  • Admins

Parameters

Name Type In Required Description
sharing_agreement_id integer Path true The ID of the sharing agreement

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/sharing_agreements/{sharing_agreement_id}.json \  -X DELETE -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/sharing_agreements/1"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/sharing_agreements/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://example.zendesk.com/api/v2/sharing_agreements/1',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/sharing_agreements/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"DELETE",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/sharing_agreements/1")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

204 No Content
// Status 204 No Content
null