Organizations

Just as agents can be segmented into groups in Zendesk, 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 simple flat JSON objects with the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the organization is created
url string yes no The API url of this organization
external_id string no no A unique external id to associate organizations to an external record
name string no yes The name of the organization
created_at date yes no The time the organization was created
updated_at date yes no The time of the last update of the organization
domain_names array no no An array of domain names associated with this organization
details string no no Any details obout the organization, such as the address
notes string no no Any notes you have about the organization
group_id integer no no New tickets from users in this organization are automatically put in this group
shared_tickets boolean no no End users in this organization are able to see each other's tickets
shared_comments boolean no no End users in this organization are able to see each other's comments on tickets
tags array no no The tags of the organization
organization_fields hash no no Custom fields for this organization
Example
{
  "id":                  35436,
  "external_id":         "ABC123",
  "url":                 "https://company.zendesk.com/api/v2/organizations/35436.json",
  "name":                "One Organization",
  "created_at":          "2009-07-20T22:55:29Z",
  "updated_at":          "2011-05-05T10:38:52Z",
  "domain_names":        ["example.com", "test.com"],
  "details":             "This is a kind of organization",
  "notes":               "",
  "group_id":            null,
  "shared_tickets":      true,
  "shared_comments":     true,
  "tags":                ["enterprise", "other_tag"],
  "organization_fields": {
    "org_dropdown": "option_1",
    "org_decimal": 5.2,
  }
}

List Organizations

GET /api/v2/organizations.json

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

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/organizations.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "organizations": [
    {
      "id":   35436,
      "name": "One Organization",
      ...
    },
    {
      "id":   20057623,
      "name": "Other Organization",
      ...
    },
  ]
}

Autocomplete Organizations

GET /api/v2/organizations/autocomplete.json?name={name}

Returns an array of organizations whose name starts with the value specified in the name parameter. The name must be at least 2 characters in length.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/autocomplete.json?name=imp \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "organizations": [
    {
      "id":   35436,
      "name": "Important Customers",
      ...
    },
    {
      "id":   20057623,
      "name": "Imperial College",
      ...
    },
  ]
}

Show Organization's Related Information

GET /api/v2/organizations/{id}/related.json

Allowed For:
  • Agents
Using curl:
curl https://{subdomain}.zendesk.com/api/v2/organizations/{id}/related.json \
  -v -u {email_address}:{password}
Example Response
Status: 200

{
  "organization_related": {
    "users_count": 4,
    "tickets_count": 12
  }
}

Show Organization

GET /api/v2/organizations/{id}.json

Allowed For
  • Admins
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "organization": {
    "id":   35436,
    "name": "My Organization",
    ...
  }
}

Show Many Organizations

GET /api/v2/organizations/show_many.json?ids={ids}

GET /api/v2/organizations/show_many.json?external_ids={external_ids}

Allowed For
  • Admins
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/show_many.json?ids=1,2 \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "organizations": [
    {
      "id":   35436,
      "name": "Important Customers",
      ...
    },
    {
      "id":   20057623,
      "name": "Imperial College",
      ...
    },
  ]
}

Create Organization

POST /api/v2/organizations.json

Allowed For
  • Admins
Using 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
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json

{
  "organization": {
    "id":   35436,
    "name": "My Organization",
    ...
  }
}

Create Many Organizations

POST /api/v2/organizations/create_many.json

Allowed For
  • Agents, with restrictions applying on certain actions
Using 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

See Job Status

Update Organization

PUT /api/v2/organizations/{id}.json

Allowed For
  • Admins
Example Request
{
  "organization": {
    "notes": "Something interesting"
  }
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json \
  -H "Content-Type: application/json" -d '{"organization": {"notes": "Something interesting"}}' \
  -v -u {email_address}:{password} -X PUT
Example Response
Status: 200 OK

{
  "organization": {
    "id":    35436,
    "name":  "My Organization",
    "notes": "Something interesting",
    ...
  }
}

Update Many Organizations

PUT /api/v2/organizations/update_many.json

PUT /api/v2/organizations/update_many.json?ids={ids}

PUT /api/v2/organizations/update_many.json?external_ids={external_ids}

Allowed For
  • Admins
Example Request

This request has two forms: * A JSON object organization may be specified. All organizations specified by the ids or external_ids parameter are updated with the fields. * A JSON array organizations may be specified, with each element specifying updates to an organization identified by id or external_id.

{
  "organization": {
    "notes": "Something interesting"
  }
}
{
  "organizations": [
    { "id": 1, "notes": "Something interesting" },
    { "external_id": "2", "notes": "Something even more interesting" }
  ]
}
Using curl
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 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

See Job Status

Delete Organization

DELETE /api/v2/organizations/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 200 OK

Bulk Delete Organizations

DELETE /api/v2/organizations/destroy_many.json?ids={ids}

DELETE /api/v2/organizations/destroy_many.json?external_ids={external_ids}

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

See Job Status

Search Organizations by External ID

GET /api/v2/organizations/search.json?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:
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/organizations/search.json?external_id={external_id} \
  -v -u {email_address}:{password}
Example Response

See Listing Organizations