Allowed For

• Agents

Returns the changes the macro would make to a ticket. It doesn’t actually
change a ticket. You can use the response data in a subsequent API call
to the Tickets endpoint to update the ticket.

The response includes only the ticket fields that would be changed by the
macro. To get the full ticket object after the macro is applied,
see Show Ticket After Changes.

Allowed For

• Agents

Lists the attachments associated with a macro.

Allowed For

• Agents

Allows an attachment to be uploaded and associated with a macro at the same time.

Note: A macro can be associated with up to five attachments.

Allowed For

• Agents

Returns the full ticket object as it would be after applying the macro to the ticket.
It doesn’t actually change the ticket.

To get only the ticket fields that would be changed by the macro,
see Show Changes to Ticket.

Allowed For

• Agents

Allowed For

• Admins

Allowed For

• Admins

Allowed For

• Admins

Allowed For

• Admins

Allowed For

• Admins

Allowed For

• Admins

Returns a list of custom organization fields in your account. Fields are returned in the order that you specify in your organization fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the key for each organization field to the values returned under the organization_fields attribute on the organization resource.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Creates any of the following custom field types:

• text (default when no “type” is specified)
• textarea
• checkbox
• date
• integer
• decimal
• regexp
• dropdown
• lookup

See About custom field types in Zendesk help.

Allowed For

• Admins

Allowed For

• Admins

Allowed for

• Admins

Allowed for

• Agents

Updating a Drop-down (Tagger) Field

Drop-down fields return an array of custom_field_options which specify the name, value, and order of drop-down options. When updating a drop-down field, note the following information:

• All options must be passed on update. Options that are not passed will be removed. As a result, these values will be removed from any organizations
• To create a new option, pass a null id along with the name and value
• To update an existing option, pass its id along with the name and value
• To reorder an option, reposition it in the custom_field_options array relative to the other options
• To remove an option, omit it from the list of options upon update

Example Request

curl https://{subdomain}.zendesk.com/api/v2/organization_fields/{organization_field_id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"organization_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 3", "value": "option_3"}]}}' \
  -v -u {email_address}:{password}

Allowed for

• Admins

Returns a list of organization memberships for the account, user or organization in question.

Note: When returning organization memberships for a user, organization memberships are sorted with the default organization first, and then by organization name.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents
• End users

Assigns a user to a given organization. Returns an error with status 422 if the user is already assigned to the organization.

Allowed For

• Admins
• Agents when creating a new organization membership for an end user

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

Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The organization_id of the unassigned tickets is set to null.

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

Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The organization_id of the unassigned tickets is set to null.

Allowed for

• Admins
• Agents when deleting an organization membership for an end user

Allowed for

• Agents

Sets the default organization membership of a given user.

Allowed for

• Admins
• Agents when setting the default organization membership for an end user

Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The organization_id of the unassigned tickets is set to null.

Allowed For

• Agents

Sets the default organization membership of a given user.

Allowed For

• Agents

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.

Allowed For:

• Agents
• End users

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

Allowed For:

• Agents
• End users

Allowed For:

• Agents
• End users

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

Retrieves the details of a specific organization merge operation. This endpoint is useful for obtaining the status and outcome of a merge that was previously initiated. It provides information such as the winning and losing organization IDs, the status of the merge, and the associated URLs.

This endpoint can be used to determine if a merge is still in progress, has completed successfully, or has encountered an error.

Allowed For

• Admins

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.

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)

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

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

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

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

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)

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.

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

Allowed For

• Admins
• Agents

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.

Allowed For

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

Allowed For

• Admins
• Agents

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

Merges two organizations by moving all users, tickets, and domain names from the organization specified by {organization_id} to the organization specified by winner_id. After the merge:

• The “losing” organization will be deleted.
• Other organization fields and their values will not be carried over to the “winning” organization.
• The merge operation creates an Organization Merge record which contains a status indicating the progress of the merge.

Note: This operation is irreversible.

Merge Statuses

Allowed For

• Admins

Retrieves a list of all organization merge operations associated with a given organization. This endpoint allows you to track the history of merge actions for an organization, including ongoing and completed merges.

Each entry in the list contains details such as the ID of the merge, the winning and losing organization IDs, the current status of the merge, and a URL to access the Organization Merge record.

Pagination

• Cursor pagination is used for this endpoint.
• A maximum of 100 records can be returned per page.

See Pagination for more details.

Allowed For

• Admins

Allowed For

• Agents

Unregisters the mobile devices that are receiving push notifications. Specify the devices as an array of mobile device tokens.

Allowed for

• Admins

Allowed for

• End Users

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Accepts a request object that sets one or more properties.

Allowed for

• End users
• Anonymous users (rate limit of 5 requests per hour for trial accounts)

Additional properties

In addition to the writable request properties in the JSON Format table above, you can set the following properties when creating a request.

Creating follow-up requests

Once a ticket is closed (as distinct from solved), it can’t be reopened. However, you can create a new request that references the closed ticket. To create the follow-up request, include a via_followup_source_id property in the request object that specifies the closed ticket. The parameter only works with closed tickets. It has no effect with other tickets.