Agents

You can use the API to get or set agent information.

If you created your Zendesk Chat account in Zendesk Support, access to the Chat Accounts and Agents APIs is restricted to GET requests. You can still use the other Chat APIs normally.

JSON Format

Agents are represented as JSON objects with the following attributes.

Name Type Read-only Description
id integer yes The ID of the agent
first_name string no The agent's first name
last_name string no The agent's last name
display_name string no The name to be displayed for the agent
create_date timestamp yes The date of creation of the agent
email integer no The email ID of the agent
roles object yes Special role privileges. See below for values (deprecated)
role_id integer no The role ID of the agent
enabled integer no Describes whether the agent is enabled
departments array yes The departments for the agent
skills array yes The skills for the agent

The roles attribute has the following values:

Value Users
owner owner of the account
administrator agent with administrator privileges

Note: The following field is required during creation:

Name Type Read-only Description
password string yes This is the password for the agent. This is only required during creation.

Get All Agents

  • GET /api/v2/agents
  • GET /api/v2/agents?since_id=100&limit=100
  • GET /api/v2/agents?max_id=150

This lists all the agents for your account.

Pagination

This endpoint uses cursor-based pagination. The records are ordered sequentially by record id. The max_id and since_id parameters act as separate cursors that track the record ids in the recordset. The max_id cursor moves backward through the recordset, with the record ids getting smaller. The since_id cursor moves forward, with the record ids getting larger.

  • Use the max_id parameter to paginate backward through the recordset. Example: "Get the previous 200 records, ending with and including the max_id record."

    "https://www.zopim.com/api/v2/agents?max_id=10&limit=200"

  • Use the since_id parameter to paginate forward through the recordset. Example: "Get the next 200 records, starting with and including the since_id record."

    "https://www.zopim.com/api/v2/agents?since_id=10&limit=200"

The next page can be retrieved by computing the next since_id by adding 1 to the ID of the last record in the current set, and specifying that as the since_id in the next request. Similarly, the previous page can be retrieved by making a request that species a max_id that is 1 less than the first element of the current record set.

Additionally, the next page and the previous page paths will be available as headers in the response.

If any of the pagination parameters (since_id, max_id, limit) are present, the default number of results is 10, but you can change it with the limit parameter. If none of the pagination parameters are present, the entire record set is returned.

Zendesk Chat recommends using pagination wherever possible. Non-paginated queries will be deprecated in subsequent releases of the API.

Allowed for
  • Owner
  • Administrator
  • Agent
Using cURL
curl "https://www.zopim.com/api/v2/agents?since_id=5&limit=2" \
  -v -u {email_address}:{password}

Note: In this example, you must enclose the URL in quotes because of the pagination parameters.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Next-Page: /api/v2/agents?since_id=9&limit=2
X-Previous-Page: /api/v2/agents?max_id=4&limit=2

[
  {
    "id" : 5,
    "first_name" : "John",
    "last_name" : "Doe",
    "display_name" : "Johnny",
    "create_date" : "2014-09-30T08:25:09Z",
    "email" : "johndoe@gmail.com",
    "roles" : {
      "owner": false,
      "administrator": false
    },
    "role_id": 3,
    "enabled" : 1,
    "departments" : []
  },
  {
    "id" : 8,
    "first_name" : "Kevin",
    "last_name" : "Doe",
    ...
  }
]

Get Agent by ID

GET /api/v2/agents/{agent_id}

Fetches an agent by his or her ID.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/{agent_id} \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id":2,
  "first_name":"Kevin",
  "last_name":"Doe",
  ...
}

Get Agent by Email ID

GET /api/v2/agents/email/{email_id}

Fetches an agent using the agent's email ID.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/{email_id} \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id":2,
  "first_name":"Kevin",
  "last_name":"Doe",
  "email":"kevin@doe.com",
  ...
}

Create Agent

POST /api/v2/agents

Allows the account owner/administrator to add more agents to the account. Note: An additional field, password, needs to be provided during creation.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents \
  -d '{
        "email": "agentsmith@agency.com",
        "password": "secretpassword",
        "first_name": "John",
        "last_name": "Smith",
        "display_name": "Smith",
        "enabled": 1
      }' \
  -v -u {email_address}:{password} \
  -X POST -H "Content-Type: application/json"
Example Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id":3,
  "first_name":"John",
  "last_name":"Smith",
  ...
}

Update Agent

PUT /api/v2/agents/{agent_id}

Allows an account owner/administrator to update details of an agent.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/{agent_id} \
  -d '{"first_name": "John", "last_name": "Smith", "role_id": 2}' \
  -v -u {email_address}:{password}
  -X PUT -H "Content-Type: application/json"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id":2,
  "first_name":"John",
  "last_name":"Smith",
  "role_id": 2,
  ...
}

Delete Agent

DELETE /api/v2/agents/{agent_id}

Allows an account owner/administrator to delete an agent.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/{agent_id} \
  -v -u {email_address}:{password} -X DELETE
Response
Status: 204 No Content

Get Requesting Agent

GET /api/v2/agents/me

Fetches information about your agent.

Allowed for
  • Owner
  • Administrator
  • Agent
Using cURL
curl https://www.zopim.com/api/v2/agents/me \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id":2,
  "first_name":"Kevin",
  "last_name":"Doe",
  ...
}

Update Requesting Agent

PUT /api/v2/agents/me

Allows an account owner/administrator to update his or her data.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/me \
  -d '{"first_name" : "Jonathan"}' \
  -v -u {email_address}:{password} \
  -X PUT -H "Content-Type: application/json"
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id":1,
  "first_name":"Jonathan",
  "last_name":"Doe",
  ...
}