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
organization_name string true false The name 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,      "organization_name": "first organization",      "updated_at": "2011-07-22T00:11:12Z",      "user_id": 29    },    {      "created_at": "2012-03-13T22:01:32Z",      "default": null,      "id": 49,      "organization_id": 3,      "organization_name": "second organization",      "updated_at": "2012-03-13T22:01:32Z",      "user_id": 155    }  ]}

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

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

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,      "organization_name": "first organization",      "updated_at": "2011-07-22T00:11:12Z",      "user_id": 29    },    {      "created_at": "2012-03-13T22:01:32Z",      "default": null,      "id": 49,      "organization_id": 3,      "organization_name": "second organization",      "updated_at": "2012-03-13T22:01:32Z",      "user_id": 155    }  ]}

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

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