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",
      ...
    }
  }
}

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": {

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

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/search.json?external_id={external_id} \
  -v -u {email_address}:{password}
Example Response

See Listing Organizations