Just as agents can be segmented into groups in Zendesk Support, your customers (end-users) can be segmented into organizations. You can manually assign customers to an organization or automatically assign them to an organization by their email address domain. Organizations can be used in business rules to route tickets to groups of agents or to send email notifications.

JSON format

Organizations are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
created_at string true false The time the organization was created
details string false false Any details obout the organization, such as the address
domain_names array false false An array of domain names associated with this organization
external_id string false false A unique external id to associate organizations to an external record. The id is case-insensitive. For example, "company1" and "Company1" are considered the same
group_id integer false false New tickets from users in this organization are automatically put in this group
id integer false false Automatically assigned when the organization is created
name string false false A unique name for the organization
notes string false false Any notes you have about the organization
organization_fields object false false Custom fields for this organization. See Custom organization fields
shared_comments boolean false false End users in this organization are able to comment on each other's tickets
shared_tickets boolean false false End users in this organization are able to see each other's tickets
tags array false false The tags of the organization
updated_at string true false The time of the last update of the organization
url string false false The API url of this organization

Custom organization fields

The examples on this page use standard fields for various requests. If you want to use custom organization fields (organization_fields) in your updates, see the organization_fields property in the following example to properly format your requests.

Example

{  "created_at": "2009-07-20T22:55:29Z",  "details": "This is a kind of organization",  "domain_names": [    "example.com",    "test.com"  ],  "external_id": "ABC123",  "group_id": null,  "id": 35436,  "name": "One Organization",  "notes": "",  "organization_fields": {    "org_decimal": 5.2,    "org_dropdown": "option_1"  },  "shared_comments": true,  "shared_tickets": true,  "tags": [    "enterprise",    "other_tag"  ],  "updated_at": "2011-05-05T10:38:52Z",  "url": "https://company.zendesk.com/api/v2/organizations/35436.json"}

List Organizations

  • GET /api/v2/organizations
  • GET /api/v2/users/{user_id}/organizations.json

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

  • Agents, with certain restrictions

If the agent has a custom agent role that restricts their access to only users in their own organization, a 403 Forbidden error is returned. See Creating custom agent roles in Zendesk help.

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations"	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/organizations")		.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/organizations',  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/organizations"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/organizations")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
{  "count": 2,  "next_page": null,  "organizations": [    {      "created_at": "2018-11-14T00:14:52Z",      "details": "caterpillar =)",      "domain_names": [        "remain.com"      ],      "external_id": "ABC198",      "group_id": 1835962,      "id": 4112492,      "name": "Groablet Enterprises",      "notes": "donkey",      "organization_fields": {        "datepudding": "2018-11-04T00:00:00+00:00",        "org_field_1": "happy happy",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "smiley",        "teapot_kettle"      ],      "updated_at": "2018-11-14T00:54:22Z",      "url": "https://example.zendesk.com/api/v2/organizations/4112492.json"    },    {      "created_at": "2017-08-14T20:13:52Z",      "details": "test",      "domain_names": [        "test.com"      ],      "external_id": "TTV273",      "group_id": null,      "id": 1873,      "name": "Willy Wonkas Chocolate Factory",      "notes": "",      "organization_fields": {        "datepudding": "2018-11-02T00:00:00+00:00",        "org_field_1": "malarky",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "teapot_kettle"      ],      "updated_at": "2019-05-16T01:27:46Z",      "url": "https://example.zendesk.com.com/api/v2/organizations/1873.json"    }  ],  "previous_page": null}

Count Organizations

  • GET /api/v2/organizations/count
  • GET /api/v2/users/{user_id}/organizations/count.json

Returns an approximate count of organizations. If the count exceeds 100,000, it is updated every 24 hours.

The refreshed_at property of the count object is a timestamp that indicates when the count was last updated.

When the count exceeds 100,000, the refreshed_at property may occasionally be null. This indicates that the count is being updated in the background and the value property of the count object is limited to 100,000 until the update is complete.

Allowed For

  • Agents

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/count.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/count"	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/organizations/count")		.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/organizations/count',  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/organizations/count"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/organizations/count")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
{  "count": {    "refreshed_at": "2020-04-06T02:18:17Z",    "value": 102  }}

Autocomplete Organizations

  • GET /api/v2/organizations/autocomplete?name={name}

Returns an array of organizations whose name starts with the value specified in the name parameter.

Pagination

  • Offset pagination only

See Using Offset Pagination.

Allowed For

  • Agents

Parameters

Name Type In Required Description
field_id string Query false The id of a lookup relationship field. The type of field is determined by the source param
name string Query true A substring of an organization to search for
source string Query false If a field_id is provided, this specifies the type of the field. For example, if the field is on a "zen:user", it references a field on a user

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/autocomplete.json?name=imp \  -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/autocomplete?field_id=&name=imp&source="	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/organizations/autocomplete")		.newBuilder()		.addQueryParameter("field_id", "")		.addQueryParameter("name", "imp")		.addQueryParameter("source", "");
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/organizations/autocomplete',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'field_id': '',    'name': 'imp',    'source': '',  },};
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/organizations/autocomplete?field_id=&name=imp&source="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/organizations/autocomplete")uri.query = URI.encode_www_form("field_id": "", "name": "imp", "source": "")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
{  "count": 2,  "next_page": null,  "organizations": [    {      "created_at": "2018-11-14T00:14:52Z",      "details": "caterpillar =)",      "domain_names": [        "remain.com"      ],      "external_id": null,      "group_id": 1835962,      "id": 35436,      "name": "Important Customers",      "notes": "donkey",      "organization_fields": {        "datepudding": "2018-11-04T00:00:00+00:00",        "org_field_1": "happy happy",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "smiley",        "teapot_kettle"      ],      "updated_at": "2018-11-14T00:54:22Z",      "url": "https://example.zendesk.com/api/v2/organizations/4112492.json"    },    {      "created_at": "2017-08-14T20:13:52Z",      "details": "test",      "domain_names": [        "test.com"      ],      "external_id": null,      "group_id": null,      "id": 20057623,      "name": "Imperial College",      "notes": "",      "organization_fields": {        "datepudding": "2018-11-02T00:00:00+00:00",        "org_field_1": "malarky",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "teapot_kettle"      ],      "updated_at": "2019-05-16T01:27:46Z",      "url": "https://example.zendesk.com.com/api/v2/organizations/1873.json"    }  ],  "previous_page": null}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "QueryError",      "title": "Invalid type:sample_type"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too many requests to autocomplete"    }  ]}
500 Internal Server Error
// Status 500 Internal Server Error
{  "errors": [    {      "code": "Unavailable",      "title": "Internal Server Error"    }  ]}

Search Organizations

  • GET /api/v2/organizations/search

Returns an array of organizations matching the criteria. You may search by an organization's external_id or name, but not both:

Searching by external_id

If you set the external_id value of an organization to associate it to an external record, you can use it to search for the organization.

For an organization to be returned, its external_id must exactly match the value provided (case insensitive).

Searching by name

For an organization to be returned, its name must exactly match the value provided (case insensitive).

Allowed For:

  • Admins
  • Agents assigned to a custom role with permissions to add or modify organizations (Enterprise only)

See Creating custom agent roles in the Support Help Center.

Parameters

Name Type In Required Description
external_id integer Query false The external id of an organization
name string Query false The name of an organization

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/search.json?external_id={external_id} \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/search?external_id=1234&name=ACME+Incorporated"	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/organizations/search")		.newBuilder()		.addQueryParameter("external_id", "1234")		.addQueryParameter("name", "ACME Incorporated");
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/organizations/search',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'external_id': '1234',    'name': 'ACME+Incorporated',  },};
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/organizations/search?external_id=1234&name=ACME+Incorporated"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/organizations/search")uri.query = URI.encode_www_form("external_id": "1234", "name": "ACME Incorporated")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
{  "count": 2,  "next_page": null,  "organizations": [    {      "created_at": "2018-11-14T00:14:52Z",      "details": "caterpillar =)",      "domain_names": [        "remain.com"      ],      "external_id": "ABC198",      "group_id": 1835962,      "id": 4112492,      "name": "Groablet Enterprises",      "notes": "donkey",      "organization_fields": {        "datepudding": "2018-11-04T00:00:00+00:00",        "org_field_1": "happy happy",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "smiley",        "teapot_kettle"      ],      "updated_at": "2018-11-14T00:54:22Z",      "url": "https://example.zendesk.com/api/v2/organizations/4112492.json"    },    {      "created_at": "2017-08-14T20:13:52Z",      "details": "test",      "domain_names": [        "test.com"      ],      "external_id": "TTV273",      "group_id": null,      "id": 1873,      "name": "Willy Wonkas Chocolate Factory",      "notes": "",      "organization_fields": {        "datepudding": "2018-11-02T00:00:00+00:00",        "org_field_1": "malarky",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "teapot_kettle"      ],      "updated_at": "2019-05-16T01:27:46Z",      "url": "https://example.zendesk.com.com/api/v2/organizations/1873.json"    }  ],  "previous_page": null}
  • GET /api/v2/organizations/{organization_id}/related

Allowed For

  • Agents

Parameters

Name Type In Required Description
organization_id integer Path true The ID of an organization

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{organization_id}/related.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/16/related"	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/organizations/16/related")		.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/organizations/16/related',  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/organizations/16/related"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/organizations/16/related")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
{  "organization_related": {    "tickets_count": 12,    "users_count": 4  }}

Show Organization

  • GET /api/v2/organizations/{organization_id}

Allowed For

  • Admins
  • Agents

Parameters

Name Type In Required Description
organization_id integer Path true The ID of an organization

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{organization_id}.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/16"	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/organizations/16")		.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/organizations/16',  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/organizations/16"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/organizations/16")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
{  "organization": {    "created_at": "2018-11-14T00:14:52Z",    "details": "caterpillar =)",    "domain_names": [      "remain.com"    ],    "external_id": null,    "group_id": 1835962,    "id": 4112492,    "name": "Groablet Enterprises",    "notes": "donkey",    "organization_fields": {      "datepudding": "2018-11-04T00:00:00+00:00",      "org_field_1": "happy happy",      "org_field_2": "teapot_kettle"    },    "shared_comments": false,    "shared_tickets": false,    "tags": [      "smiley",      "teapot_kettle"    ],    "updated_at": "2018-11-14T00:54:22Z",    "url": "https://example.zendesk.com/api/v2/organizations/4112492.json"  }}

Show Many Organizations

  • GET /api/v2/organizations/show_many

Accepts a comma-separated list of up to 100 organization ids or external ids.

Allowed For

  • Admins
  • Agents

Parameters

Name Type In Required Description
external_ids string Query false A list of external ids
ids string Query false A list of organization ids

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/show_many.json?ids=35436,20057623 \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/show_many?external_ids=1764%2C42156&ids=35436%2C20057623"	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/organizations/show_many")		.newBuilder()		.addQueryParameter("external_ids", "1764,42156")		.addQueryParameter("ids", "35436,20057623");
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/organizations/show_many',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'external_ids': '1764%2C42156',    'ids': '35436%2C20057623',  },};
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/organizations/show_many?external_ids=1764%2C42156&ids=35436%2C20057623"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/organizations/show_many")uri.query = URI.encode_www_form("external_ids": "1764,42156", "ids": "35436,20057623")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
{  "count": 2,  "next_page": null,  "organizations": [    {      "created_at": "2018-11-14T00:14:52Z",      "details": "caterpillar =)",      "domain_names": [        "remain.com"      ],      "external_id": null,      "group_id": 1835962,      "id": 35436,      "name": "Important Customers",      "notes": "donkey",      "organization_fields": {        "datepudding": "2018-11-04T00:00:00+00:00",        "org_field_1": "happy happy",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "smiley",        "teapot_kettle"      ],      "updated_at": "2018-11-14T00:54:22Z",      "url": "https://example.zendesk.com/api/v2/organizations/4112492.json"    },    {      "created_at": "2017-08-14T20:13:52Z",      "details": "test",      "domain_names": [        "test.com"      ],      "external_id": null,      "group_id": null,      "id": 20057623,      "name": "Imperial College",      "notes": "",      "organization_fields": {        "datepudding": "2018-11-02T00:00:00+00:00",        "org_field_1": "malarky",        "org_field_2": "teapot_kettle"      },      "shared_comments": false,      "shared_tickets": false,      "tags": [        "teapot_kettle"      ],      "updated_at": "2019-05-16T01:27:46Z",      "url": "https://example.zendesk.com.com/api/v2/organizations/1873.json"    }  ],  "previous_page": null}

Create Organization

  • POST /api/v2/organizations

You must provide a unique name for each organization. Normally the system doesn't allow records to be created with identical names. However, a race condition can occur if you make two or more identical POSTs very close to each other, causing the records to have identical organization names.

Allowed For

  • Admins
  • Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations.json \  -H "Content-Type: application/json" -d '{"organization": {"name": "My Organization"}}' \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations"	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/organizations")		.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/organizations',  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/organizations"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/organizations")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
{  "organization": {    "created_at": "2020-09-30T01:50:12Z",    "details": null,    "domain_names": [],    "external_id": null,    "group_id": null,    "id": 23409462,    "name": "My Organization",    "notes": null,    "organization_fields": null,    "shared_comments": false,    "shared_tickets": false,    "tags": [],    "updated_at": "2020-09-30T01:50:12Z",    "url": "https://example.zendesk.com/api/v2/organizations/23409462.json"  }}

Create Many Organizations

  • POST /api/v2/organizations/create_many

Accepts an array of up to 100 organization objects.

Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See Job limit for more information.

Allowed For

  • Agents, with restrictions applying on certain actions

Code Samples

curl
curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/organizations/create_many.json \  -H "Content-Type: application/json" -X POST -d '{"organizations": [{"name": "Org1"}, {"name": "Org2"}]}'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/create_many"	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/organizations/create_many")		.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/organizations/create_many',  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/organizations/create_many"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/organizations/create_many")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)

200 OK
// Status 200 OK
{  "job_status": {    "id": "8b726e606741012ffc2d782bcb7848fe",    "message": "Completed at Fri Apr 13 02:51:53 +0000 2012",    "progress": 2,    "results": [      {        "action": "update",        "id": 380,        "status": "Updated",        "success": true      }    ],    "status": "completed",    "total": 2,    "url": "https://company.zendesk.com/api/v2/job_statuses/8b726e606741012ffc2d782bcb7848fe.json"  }}

Create Or Update Organization

  • POST /api/v2/organizations/create_or_update

Creates an organization if it doesn't already exist, or updates an existing organization. Using this method means one less call to check if an organization exists before creating it. You need to specify the id or external id when updating an organization to avoid a duplicate error response. Name is not available as a matching criteria.

Allowed For

  • Agents, with restrictions on certain actions

Code Samples

curl

Existing organization identified by ID

curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/organizations/create_or_update.json \  -H "Content-Type: application/json" -X POST -d '{"organization": {"id": "123", "name": "My Organization"}}'
curl

Existing organization identified by external ID

curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/organizations/create_or_update.json \  -H "Content-Type: application/json" -X POST -d '{"organization": {"external_id": "abc_123", "name": "My Organization"}}'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/create_or_update"	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/organizations/create_or_update")		.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/organizations/create_or_update',  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/organizations/create_or_update"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/organizations/create_or_update")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)

200 OK
// Status 200 OK
{  "organization": {    "created_at": "2020-09-30T01:50:12Z",    "details": null,    "domain_names": [],    "external_id": null,    "group_id": null,    "id": 23409462,    "name": "My Organization",    "notes": null,    "organization_fields": null,    "shared_comments": false,    "shared_tickets": false,    "tags": [],    "updated_at": "2020-09-30T01:50:12Z",    "url": "https://example.zendesk.com/api/v2/organizations/23409462.json"  }}
201 Created
// Status 201 Created
{  "organization": {    "created_at": "2020-09-30T01:50:12Z",    "details": null,    "domain_names": [],    "external_id": null,    "group_id": null,    "id": 23409462,    "name": "My Organization",    "notes": null,    "organization_fields": null,    "shared_comments": false,    "shared_tickets": false,    "tags": [],    "updated_at": "2020-09-30T01:50:12Z",    "url": "https://example.zendesk.com/api/v2/organizations/23409462.json"  }}

Update Organization

  • PUT /api/v2/organizations/{organization_id}

Allowed For

  • Admins
  • Agents

Agents with no permissions restrictions can only update "notes" on organizations.

Note: Updating an organization's domain_names property overwrites all existing domain_names values. To prevent this, submit a complete list of domain_names for the organization in your request.

Example Request

{  "organization": {    "notes": "Something interesting"  }}

Parameters

Name Type In Required Description
organization_id integer Path true The ID of an organization

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{organization_id}.json \  -H "Content-Type: application/json" -d '{"organization": {"notes": "Something interesting"}}' \  -v -u {email_address}:{password} -X PUT
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/16"	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/organizations/16")		.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/organizations/16',  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/organizations/16"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/organizations/16")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
{  "organization": {    "created_at": "2018-11-14T00:14:52Z",    "details": "caterpillar =)",    "domain_names": [      "remain.com"    ],    "external_id": null,    "group_id": 1835962,    "id": 4112492,    "name": "Groablet Enterprises",    "notes": "Something Interesting",    "organization_fields": {      "datepudding": "2018-11-04T00:00:00+00:00",      "org_field_1": "happy happy",      "org_field_2": "teapot_kettle"    },    "shared_comments": false,    "shared_tickets": false,    "tags": [      "smiley",      "teapot_kettle"    ],    "updated_at": "2018-11-14T00:54:22Z",    "url": "https://example.zendesk.com/api/v2/organizations/4112492.json"  }}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too many requests to update"    }  ]}

Update Many Organizations

  • PUT /api/v2/organizations/update_many

Bulk or batch updates up to 100 organizations.

Bulk update

To make the same change to multiple organizations, use the following endpoint and data format:

https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json?ids=1,2,3

{  "organization": {    "notes": "Priority"  }}

Batch update

To make different changes to multiple organizations, use the following endpoint and data format:

https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json

{  "organizations": [    { "id": 1, "notes": "Priority" },    { "id": 2, "notes": "Normal" }  ]}

Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See Job limit for more information.

Allowed For

  • Admins
  • Agents

Agents with no permissions restrictions can only update "notes" on organizations.

Parameters

Name Type In Required Description
external_ids string Query false A list of external ids
ids string Query false A list of organization ids

Code Samples

curl

Specifying existing organizations by query parameter

curl https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json?ids=1,2 \  -H "Content-Type: application/json" \  -v -u {email_address}:{password} -X PUT \  -d '{"organization": {"notes": "Something interesting"}}'
curl

Specifying existing organizations by payload

curl https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json \  -H "Content-Type: application/json" \  -v -u {email_address}:{password} -X PUT \  -d '{"organizations": [{"id": "1", "notes": "Something interesting"}, {"external_id": "2", "notes": "Something even more interesting"}]}'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/update_many?external_ids=1764%2C42156&ids=35436%2C20057623"	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/organizations/update_many")		.newBuilder()		.addQueryParameter("external_ids", "1764,42156")		.addQueryParameter("ids", "35436,20057623");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/organizations/update_many',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'external_ids': '1764%2C42156',    'ids': '35436%2C20057623',  },};
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/organizations/update_many?external_ids=1764%2C42156&ids=35436%2C20057623"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/organizations/update_many")uri.query = URI.encode_www_form("external_ids": "1764,42156", "ids": "35436,20057623")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
{  "job_status": {    "id": "8b726e606741012ffc2d782bcb7848fe",    "message": "Completed at Fri Apr 13 02:51:53 +0000 2012",    "progress": 2,    "results": [      {        "action": "update",        "id": 380,        "status": "Updated",        "success": true      }    ],    "status": "completed",    "total": 2,    "url": "https://company.zendesk.com/api/v2/job_statuses/8b726e606741012ffc2d782bcb7848fe.json"  }}

Delete Organization

  • DELETE /api/v2/organizations/{organization_id}

Allowed For

  • Admins
  • Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

Parameters

Name Type In Required Description
organization_id integer Path true The ID of an organization

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{organization_id}.json \  -v -u {email_address}:{password} -X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/16"	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/organizations/16")		.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/organizations/16',  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/organizations/16"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/organizations/16")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

Bulk Delete Organizations

  • DELETE /api/v2/organizations/destroy_many

Accepts a comma-separated list of up to 100 organization ids or external ids.

Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See Job limit for more information.

Allowed For

  • Admins
  • Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

Parameters

Name Type In Required Description
external_ids string Query false A list of external ids
ids string Query false A list of organization ids

Code Samples

curl

Existing organizations identified by ID

curl https://{subdomain}.zendesk.com/api/v2/organizations/destroy_many.json?ids=1,2,3 \  -v -u {email_address}:{password} -X DELETE
curl

Existing organizations identified by external ID

curl https://{subdomain}.zendesk.com/api/v2/organizations/destroy_many.json?external_ids=1,2,3 \  -v -u {email_address}:{password} -X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/organizations/destroy_many?external_ids=1764%2C42156&ids=35436%2C20057623"	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/organizations/destroy_many")		.newBuilder()		.addQueryParameter("external_ids", "1764,42156")		.addQueryParameter("ids", "35436,20057623");
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/organizations/destroy_many',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'external_ids': '1764%2C42156',    'ids': '35436%2C20057623',  },};
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/organizations/destroy_many?external_ids=1764%2C42156&ids=35436%2C20057623"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/organizations/destroy_many")uri.query = URI.encode_www_form("external_ids": "1764,42156", "ids": "35436,20057623")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)

200 OK
// Status 200 OK
{  "job_status": {    "id": "82de0b044094f0c67893ac9fe64f1a99",    "message": "Completed at 2018-03-08 10:07:04 +0000",    "progress": 2,    "results": [      {        "action": "delete",        "id": 244,        "status": "Deleted",        "success": true      },      {        "action": "delete",        "id": 245,        "status": "Deleted",        "success": true      }    ],    "status": "completed",    "total": 2,    "url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"  }}