Organizations
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 |
shared_comments | boolean | false | false | End users in this organization are able to see each other's comments on 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 |
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.
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations.json \
-v -u {email_address}:{password}
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
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/count.json \
-v -u {email_address}:{password}
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
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 |
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/autocomplete.json?name=imp \
-u {email_address}:{password}
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 by External ID
GET /api/v2/organizations/search?external_id={external_id}
If you set the external_id
value of an organization to associate it to an external record, you can use the external id to search for the organization.
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 | true | The external id of an organization |
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/search.json?external_id={external_id} \
-v -u {email_address}:{password}
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
}
Show Organization's Related Information
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 |
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{organization_id}/related.json \
-v -u {email_address}:{password}
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 |
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{organization_id}.json \
-v -u {email_address}:{password}
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 |
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/show_many.json?ids=35436,20057623 \
-v -u {email_address}:{password}
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
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}
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.
Allowed For
- Agents, with restrictions applying on certain actions
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"}]}'
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 identified by ID or external ID. Using this method means one less call to check if an organization exists before creating it.
Allowed For
- Agents, with restrictions on certain actions
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"}}'
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 overwrites all existing domain_names
values. To prevent this, submit a complete list of domain_names
associated with 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 |
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
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.
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 |
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"}]}'
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
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
organization_id | integer | Path | true | The ID of an organization |
curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{organization_id}.json \
-v -u {email_address}:{password} -X DELETE
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.
Allowed For
- Admins
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 |
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
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"
}
}