Get Contact List | LiveDesk API Contact

Developers can use this API to query the list of contacts under an account.

Request Method

GET

Endpoint

https://livedesk-api.engagelab.com/api/v2/accounts/contacts

Authentication

For details, see the authentication instructions in API Overview.

Request

Request Example

curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/contacts?include_contact_inboxes=false&page=1&sort=last_activity_at&page_size=10' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)'

              
              curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/contacts?include_contact_inboxes=false&page=1&sort=last_activity_at&page_size=10' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'

This code block in the floating window

Request Headers

Field	Type	Description
Authorization	string	Authenticate using `Authorization: Basic base64(API Key:API Secret)`. Go to the API Keys page to obtain the API Key and API Secret, connect them with a colon, and encode them in Base64.
Content-Type	application/json	Data type. Use `application/json` for regular text messages.

Query Parameters

Field	Type	Required	Description
page	integer	No	Page number. The default is 1, with 15 items per page.
labels	string / string[]	No	Filter by labels. Multiple labels are supported; contacts matching any label are returned.
include_contact_inboxes	boolean	No	Whether to return `contact_inboxes`. The default is `true`.
sort	string	No	Sorting field. Available values: `email`, `name`, `phone_number`, `last_activity_at`, `created_at`, `company`, `city`, and `country`.
direction	string	No	Sort direction: `asc` or `desc`.

Successful Response

Response Example

{ "meta": { "count": 1, "current_page": "1" }, "payload": [ { "additional_attributes": { "city": "", "country": "", "telegram": "", "description": "", "company_name": "", "country_code": "", "social_profiles": { "github": "", "twitter": "", "facebook": "", "linkedin": "", "instagram": "" } }, "availability_status": "offline", "email": "support@jiguang.cn", "id": 318763, "name": "support", "phone_number": null, "blocked": false, "identifier": "4444", "thumbnail": "", "custom_attributes": {}, "last_activity_at": 1765441908, "created_at": 1765441895, "contact_inboxes": [ { "source_id": "src_001", "inbox": { "id": 10, "name": "Customer Service Channel", "channel_type": "Channel::Api" } } ] } ] }

              
              {
  "meta": {
    "count": 1,
    "current_page": "1"
  },
  "payload": [
    {
      "additional_attributes": {
        "city": "",
        "country": "",
        "telegram": "",
        "description": "",
        "company_name": "",
        "country_code": "",
        "social_profiles": {
          "github": "",
          "twitter": "",
          "facebook": "",
          "linkedin": "",
          "instagram": ""
        }
      },
      "availability_status": "offline",
      "email": "support@jiguang.cn",
      "id": 318763,
      "name": "support",
      "phone_number": null,
      "blocked": false,
      "identifier": "4444",
      "thumbnail": "",
      "custom_attributes": {},
      "last_activity_at": 1765441908,
      "created_at": 1765441895,
      "contact_inboxes": [
        {
          "source_id": "src_001",
          "inbox": {
            "id": 10,
            "name": "Customer Service Channel",
            "channel_type": "Channel::Api"
          }
        }
      ]
    }
  ]
}

This code block in the floating window

contact_inboxes is returned when include_contact_inboxes=true.

Response Parameters

Field	Type	Required	Description
meta	Object	No	Metadata object.
count	Integer	No	Count of query results.
current_page	Integer	No	Page number of the current query results.
payload	Object	No	Contact attributes.
additional_attributes	Object	No	Additional attributes.
availability_status	String	No	Online status. The default is `offline`.
email	String	No	Email address.
id	Integer	No	Contact ID.
name	String	No	Name.
phone_number	String	No	Phone number.
blocked	Boolean	No	Whether the contact is blocked. The default is `false`.
identifier	String	No	User identifier.
thumbnail	String	No	User thumbnail.
custom_attributes	Object	No	Custom attributes.
created_at	String	No	Timestamp when the contact was created.
last_activity_at	String	No	Timestamp of the last activity.
contact_inboxes	Array	No	Contact channel information, returned only when `include_contact_inboxes=true`.
source_id	String	No	Source ID.
inbox	Object	No	Inbox information.
id	Integer	No	Inbox ID.
name	String	No	Inbox name.
channel_type	String	No	Channel type.

Error Response

Response Parameters

HTTP Status Code	Description
401	Unauthorized. The token is invalid or missing.
403	Insufficient permissions.