This documentation represents an early alpha-version API. The Maqsam API is subject to change in the future.

Agents API Documentation


All calls are authenticated with HTTP Basic Authentication. This allows for using curl -u "<access_key_id>:<access_secret>" during testing.

Contact to enable the API feature for your account, then you can generate access_key_id and access_secret combination from the account settings.


The index endpoint is served on: It will return a paginated list with a maximum of 100 entries per page of agents data including both active and inactive agents.


Calls to this endpoint use the HTTP GET verb, with MIME type application/x-www-form-urlencoded.

Request params are: * page (optional): to specify the page number which its data is returned. 0 and 1 values will return the same page. Must be provided in the url:<page> If it is not provided, the default is 0 i.e the first page. The following three requests will return the same data: - - -


In Case of Failure

If the API call fails, it returns an HTTP status code of 401, or 500, and a JSON body with a message specifying the nature of the failure, for example:


The following table shows all the possible failure scenarios, and their associated messages and HTTP status codes.

ReasonStatus CodeMessage
Authentication fails401"Unauthorized"
In case of server-side error500"Internal Server Error"

In Case of Success

If the API call is successful, it returns an HTTP status code of 200, with the following JSON body, the message value is an array where each element represents an agent record

  "result": "success", 
  "message": "<array of agents>"

Where each element of < array of agents > contains the following fields:

  • identifier: a unique identifier of the agent.
  • name: name of the agent.
  • email: email of the agent.
  • active: boolean value representing whether agent is active or inactive.
  • groups: the agents' groups.
  • outgoingEnabled: boolean value representing whether outgoing calls are enabled for this agent.
  • incomingEnabled: boolean value representing whether incoming calls are enabled for this agent.
  • whatsappEnabled: boolean value representing whether whatsapp conversations are enabled for this agent.
  • state: agent state in addition to timestamp representing the starting time of the state, state could be Available, Busy, Absent or any other user-defined state.
  • created_at: Epoch time of the agent creation.