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.

Agents are represented as JSON objects with the following attributes.

The roles attribute has the following values:

Note: The following field is required during creation:

• 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.

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.

• Owner
• Administrator
• Agent

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.

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 /api/v2/agents/{agent_id}

Fetches an agent by his or her ID.

• Owner
• Administrator

curl https://www.zopim.com/api/v2/agents/{agent_id} \
  -v -u {email_address}:{password}

HTTP/1.1 200 OK
Content-Type: application/json

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

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

Fetches an agent using the agent's email ID.

• Owner
• Administrator

curl https://www.zopim.com/api/v2/agents/{email_id} \
  -v -u {email_address}:{password}

HTTP/1.1 200 OK
Content-Type: application/json

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

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.

• Owner
• Administrator

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"

HTTP/1.1 201 Created
Content-Type: application/json

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

PUT /api/v2/agents/{agent_id}

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

• Owner
• Administrator

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"

HTTP/1.1 200 OK
Content-Type: application/json

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

DELETE /api/v2/agents/{agent_id}

Allows an account owner/administrator to delete an agent.

• Owner
• Administrator

curl https://www.zopim.com/api/v2/agents/{agent_id} \
  -v -u {email_address}:{password} -X DELETE

Status: 204 No Content

GET /api/v2/agents/me

Fetches information about your agent.

• Owner
• Administrator
• Agent

curl https://www.zopim.com/api/v2/agents/me \
  -v -u {email_address}:{password}

HTTP/1.1 200 OK
Content-Type: application/json

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

PUT /api/v2/agents/me

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

• Owner
• Administrator

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"

HTTP/1.1 200 OK
Content-Type: application/json

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