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