Look Up Conversations by Contact Identifier

External systems can look up the associated regular conversation IDs, creation times, and current statuses for a contact using the contact's business identifier, email address, or full phone number. The returned conversation IDs can be used directly with existing V2 APIs for conversation details, messages, and more.

Request Method

GET

Request URL

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup

Authentication

This API uses HTTP Basic authentication. Pass Authorization in the request header, with the API key as the username and the API secret as the password. The project associated with the credentials defines the lookup scope, so you do not need to include the project ID in the path. For details, see API Overview.

If account_id is included in the request, its value must match the project associated with the credentials; otherwise, 401 is returned.

Request

Request Example

              
              curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'

            

When looking up by phone number, + must be URL-encoded:

              
              GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

            

Request Header Parameters

Query Parameters

Matching Rules

• identifier: Case-sensitive. The original value is preserved, and substring or wildcard matching is not supported.
• email: Leading and trailing whitespace is removed, and the email format is validated before an exact, case-insensitive match is performed.
• phone: Leading and trailing whitespace is removed first. The number must be complete, include + and the country code, and match the format of the contact's phone_number. The API does not add a default country code or support matching by the last digits of a number.
• GET parameters must be URL-encoded correctly. In particular, + in phone numbers should be encoded as %2B.

Lookup Scope and Sorting

Contacts and conversations are looked up only within the project associated with the credentials. The API returns all regular conversations associated with the contact across all inboxes in the project (conversation_category=chat), excluding ticket conversations and without filtering by the current agent, assignee, or inbox.

Regular conversations in all statuses are returned: open, resolved, pending, snoozed, and closed. This API does not provide status filtering; even if status is provided, the results are not narrowed.

Results are sorted by conversation creation time in descending order. When creation times are the same, results are sorted by the internal conversation primary key in descending order. The pagination order remains stable as long as the data does not change. Page-based pagination does not guarantee a consistent snapshot while conversations are being created or deleted concurrently.

Response

Successful Response

HTTP 200:

              
              {
  "meta": {
    "count": 2,
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1
  },
  "payload": [
    {
      "id": 202609000000002,
      "created_at": 1788739200,
      "status": "closed",
      "inbox_id": 12,
      "contact_id": 901
    },
    {
      "id": 202609000000001,
      "created_at": 1788652800,
      "status": "open",
      "inbox_id": 10,
      "contact_id": 901
    }
  ]
}

            

Response Parameters

If the contact does not exist, the contact has no regular conversations, or the requested page exceeds the total number of pages, HTTP 200 is returned. In all three cases, payload is an empty array; meta.count always retains the actual total number of results.

The response contains only the fields listed above and does not return messages, attachments, or personal contact information.

Error Response

Error responses use the following structure. Error descriptions do not echo the lookup value:

              
              {
  "error": "Error description"
}

            

Usage Notes

• This API only adds lookup functionality and does not modify contact or conversation data.
• The API does not support finding contacts through fuzzy matching. Make sure the identifier, email address, or phone number stored by the external system matches the corresponding contact attribute in LiveDesk.
• To process conversations in the lookup results, use payload[].id from the response as the external conversation ID when calling the corresponding V2 APIs.