Search Contacts | LiveDesk API Contact

Developers can use the LiveDesk API to query the list of contacts in an account and search by contact email, phone number, name, or identifier.

Request Method

GET

Request URL

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?q=support@engagelab.com' \ -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?q=support@engagelab.com' \
-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 plain-text messages.

Query Parameters

Field	Type	Required	Description
q	string	No	Query parameter. Contact attribute fields include `email`, `phone_number`, `name`, and `identifier`.
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	Sort field. Available values: `email`, `name`, `phone_number`, `last_activity_at`, `created_at`, `company`, `city`, and `country`.
direction	string	No	Sort direction: `asc` or `desc`.

Response Example

{ "meta": { "count": 1, "current_page": 1 }, "payload": [ { "additional_attributes": { "source_id": "email:ed5c8362-425c-4589-8adb-61a033d8c5fb.support@engagelab.com" }, "availability_status": "offline", "email": "support@engagelab.com", "id": 64464046, "name": "support", "phone_number": null, "blocked": false, "identifier": null, "thumbnail": "", "custom_attributes": {}, "last_activity_at": 1778572024, "created_at": 1778570103, "contact_inboxes": [ { "source_id": "support@engagelab.com", "inbox": { "id": 985, "channel_id": 107, "name": "Email", "channel_type": "Channel::Email", "provider": null } } ] } ] }

              
              {
    "meta": {
        "count": 1,
        "current_page": 1
    },
    "payload": [
        {
            "additional_attributes": {
                "source_id": "email:ed5c8362-425c-4589-8adb-61a033d8c5fb.support@engagelab.com"
            },
            "availability_status": "offline",
            "email": "support@engagelab.com",
            "id": 64464046,
            "name": "support",
            "phone_number": null,
            "blocked": false,
            "identifier": null,
            "thumbnail": "",
            "custom_attributes": {},
            "last_activity_at": 1778572024,
            "created_at": 1778570103,
            "contact_inboxes": [
                {
                    "source_id": "support@engagelab.com",
                    "inbox": {
                        "id": 985,
                        "channel_id": 107,
                        "name": "Email",
                        "channel_type": "Channel::Email",
                        "provider": null
                    }
                }
            ]
        }
    ]
}

This code block in the floating window

Response Parameters

Field	Type	Required	Description
count	Int	No	Count of query results.
current_page	Int	No	Page number of the query results.
payload	Object	No	Property structure.
additional_attributes	Object	No	Additional attributes.
availability_status	String	No	Online status. The default is `offline`.
email	String	No	Email address.
id	String	No	Contact ID.
name	String	No	Name.
phone_number	String	No	Phone number.
blocked	String	No	Whether the contact is blocked. The default is `false`.
identifier	String	No	The contact's external unique identifier, corresponding to the User ID displayed in the interface.
thumbnail	String	No	Avatar URL.
custom_attributes	String	No	Contact attributes.
created_at	String	No	Creation timestamp.
last_activity_at	String	No	Latest update timestamp.
contact_inboxes	Array	No	Associated channel information, returned only when `include_contact_inboxes=true`.
source_id	String	No	Channel ID.
inbox	Object	No	Channel information.
id	String	No	Channel ID.
name	String	No	Channel name.
channel_type	String	No	Channel type.
provider	String	No	Provider. For example, when the channel is WhatsApp, the value is `whatsapp_cloud`, `engagelab_whatsapp`, or `twilio`. For channels without a specific provider, the value is `null`.