Agents in an organization can subscribe to be notified whenever someone in their organization submits a ticket. The agents will be notified as long as they're allowed to see all tickets or the organization's tickets. See Setting agent privileges and defining ticket access in the Zendesk Support knowledge base.

End users can also subscribe to be notified if they're members of a shared organization. See Setting up a shared organization for end-users and Viewing and editing a user's profile in the knowledge base.

JSON format

Organization Subscriptions are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
created_atstringfalsefalseThe date the organization subscription was created
idintegerfalsefalseThe ID of the organization subscription
organization_idintegerfalsefalseThe ID of the organization
user_idintegerfalsefalseThe ID of the user

Example

{  "created_at": "2009-07-20T22:55:29Z",  "id": 1234,  "organization_id": 32,  "user_id": 482}

List Organization Subscriptions

  • GET /api/v2/organization_subscriptions
  • GET /api/v2/organizations/{organization_id}/subscriptions
  • GET /api/v2/users/{user_id}/organization_subscriptions

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For:

  • Agents
  • End users

For end users, the response will only list the subscriptions created by the requesting end user.

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/organization_subscriptions.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organization_subscriptions"	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 "{email_address}/token:{api_token}"
	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/organization_subscriptions")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/organization_subscriptions',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/organization_subscriptions"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/organization_subscriptions")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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
{  "organization_subscriptions": [    {      "created_at": "2009-07-20T22:55:29Z",      "id": 1234,      "organization_id": 32,      "user_id": 482    },    {      "created_at": "2011-08-22T21:12:09Z",      "id": 43681,      "organization_id": 334,      "user_id": 49471    }  ]}

Show Organization Subscription

  • GET /api/v2/organization_subscriptions/{organization_subscription_id}

Allowed For:

  • Agents
  • End users

For end users, the response will only list the subscriptions created by the requesting end user.

Parameters

NameTypeInRequiredDescription
organization_subscription_idintegerPathtrueThe ID of the organization subscription

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/organization_subscriptions/{organization_subscription_id}.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organization_subscriptions/35436"	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 "{email_address}/token:{api_token}"
	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/organization_subscriptions/35436")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/organization_subscriptions/35436',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/organization_subscriptions/35436"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/organization_subscriptions/35436")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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
{  "organization_subscription": {    "created_at": "2009-07-20T22:55:29Z",    "id": 1234,    "organization_id": 32,    "user_id": 482  }}

Create Organization Subscription

  • POST /api/v2/organization_subscriptions

Allowed For:

  • Agents
  • End users

End users can only subscribe to shared organizations in which they're members.

Example body

{  "organization_subscription": {    "organization_id": 32,    "user_id": 482  }}

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/organization_subscriptions.json \  -d '{"organization_subscription": {"user_id": 772, "organization_id": 881}}' \  -v -u {email_address}/token:{api_token} -H "Content-Type: application/json" -X POST
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://example.zendesk.com/api/v2/organization_subscriptions"	method := "POST"	payload := strings.NewReader(`{  "organization_subscription": {    "organization_id": 32,    "user_id": 482  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	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/organization_subscriptions")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"organization_subscription\": {    \"organization_id\": 32,    \"user_id\": 482  }}""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "organization_subscription": {    "organization_id": 32,    "user_id": 482  }});
var config = {  method: 'POST',  url: 'https://example.zendesk.com/api/v2/organization_subscriptions',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport jsonfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/organization_subscriptions"
payload = json.loads("""{  "organization_subscription": {    "organization_id": 32,    "user_id": 482  }}""")headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"POST",	url,	auth=auth,	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/organization_subscriptions")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "organization_subscription": {    "organization_id": 32,    "user_id": 482  }})email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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
{  "organization_subscription": {    "created_at": "2009-07-20T22:55:29Z",    "id": 1234,    "organization_id": 32,    "user_id": 482  }}

Delete Organization Subscription

  • DELETE /api/v2/organization_subscriptions/{organization_subscription_id}

Allowed For:

  • Agents
  • End users

Parameters

NameTypeInRequiredDescription
organization_subscription_idintegerPathtrueThe ID of the organization subscription

Code Samples

cURL
curl https://{subdomain}.zendesk.com/api/v2/organization_subscriptions/{organization_subscription_id}.json \-v -u {email_address}/token:{api_token} -X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organization_subscriptions/35436"	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 "{email_address}/token:{api_token}"
	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/organization_subscriptions/35436")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://example.zendesk.com/api/v2/organization_subscriptions/35436',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/organization_subscriptions/35436"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"DELETE",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/organization_subscriptions/35436")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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