Support API

Organization Memberships

A membership links a user to an organization. Organizations can have many users. Users can be in many organizations if the account supports multiple organizations. You can use the API to list users in an organization, and reassign organization members.

JSON Format

Organization Memberships are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
created_at string true false When this record was created
default boolean false true Denotes whether this is the default organization membership for the user. If false, returns null
id integer true false Automatically assigned when the membership is created
organization_id integer true true The ID of the organization associated with this user, in this membership
updated_at string true false When this record last got updated
url string true false The API url of this membership
user_id integer true true The ID of the user for whom this memberships belongs
Example
 
{
  "created_at": "2009-05-13T00:07:08Z",
  "default": true,
  "id": 4,
  "organization_id": 12,
  "updated_at": "2011-07-22T00:11:12Z",
  "url": "https://example.zendesk.com/api/v2/organization_memberships/4.json",
  "user_id": 29
}

List Memberships
  • GET /api/v2/organization_memberships
  • GET /api/v2/users/{user_id}/organization_memberships.json
  • GET /api/v2/organizations/{organization_id}/organization_memberships.json

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/organization_memberships.json \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

{
  "organization_memberships": [
    {
      "created_at": "2009-05-13T00:07:08Z",
      "default": true,
      "id": 4,
      "organization_id": 12,
      "updated_at": "2011-07-22T00:11:12Z",
      "user_id": 29
    },
    {
      "created_at": "2012-03-13T22:01:32Z",
      "default": null,
      "id": 49,
      "organization_id": 3,
      "updated_at": "2012-03-13T22:01:32Z",
      "user_id": 155
    }
  ]
}

Create Membership
  • POST /api/v2/organization_memberships
  • POST /api/v2/users/{user_id}/organization_memberships

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

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/organization_memberships.json \
  -X POST -d '{"organization_membership": {"user_id": 72, "organization_id": 88}}' \
  -H "Content-Type: application/json" -v -u {email_address}:{password}
Example Response
 
Status 201 Created

{
  "organization_membership": {
    "created_at": "2012-04-03T12:34:01Z",
    "default": true,
    "id": 461,
    "organization_id": 88,
    "updated_at": "2012-04-03T12:34:01Z",
    "user_id": 72
  }
}

Create Many Memberships
  • POST /api/v2/organization_memberships/create_many

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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/organization_memberships/create_many.json \
  -H "Content-Type: application/json" \
  -d '{"organization_memberships": [{"user_id": 72, "organization_id": 88}, {"user_id": 27, "organization_id": 88}]}' \
  -v -u {email_address}:{password} -X POST
Example Response
 
Status 200 OK

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

Bulk Delete Memberships
  • DELETE /api/v2/organization_memberships/destroy_many

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.

Allowed For
  • Agents
Parameters
Name Type In Required Description
ids array Query false The IDs of the organization memberships to delete
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/organization_memberships/destroy_many.json?ids=1,2,3 \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
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"
  }
}

Show Membership
  • GET /api/v2/organization_memberships/{organization_membership_id}
  • GET /api/v2/users/{user_id}/organization_memberships/{organization_membership_id}.json
Allowed For
  • End Users
Parameters
Name Type In Required Description
organization_membership_id integer Path true The ID of the organization membership
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/organization_memberships/{organization_membership_id}.json \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

{
  "organization_membership": {
    "created_at": "2009-05-13T00:07:08Z",
    "default": true,
    "id": 4,
    "organization_id": 12,
    "updated_at": "2011-07-22T00:11:12Z",
    "user_id": 29
  }
}

Delete Membership
  • DELETE /api/v2/organization_memberships/{organization_membership_id}
  • DELETE /api/v2/users/{user_id}/organization_memberships/{organization_membership_id}.json

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
Parameters
Name Type In Required Description
organization_membership_id integer Path true The ID of the organization membership
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/organization_memberships/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
Status 204 No Content

Set Membership as Default
  • PUT /api/v2/users/{user_id}/organization_memberships/{organization_membership_id}/make_default

Sets the default organization membership of a given user.

Allowed For
  • Agents
Parameters
Name Type In Required Description
organization_membership_id integer Path true The ID of the organization membership
user_id integer Path true The ID of the user
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/organization_memberships/{organization_membership_id}/make_default.json \
  -v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"
Example Response
 
Status 200 OK

{
  "organization_memberships": [
    {
      "created_at": "2009-05-13T00:07:08Z",
      "default": true,
      "id": 4,
      "organization_id": 12,
      "updated_at": "2011-07-22T00:11:12Z",
      "user_id": 29
    },
    {
      "created_at": "2012-03-13T22:01:32Z",
      "default": null,
      "id": 49,
      "organization_id": 3,
      "updated_at": "2012-03-13T22:01:32Z",
      "user_id": 155
    }
  ]
}