​
Query Contacts

This endpoint retrieves a list of contacts associated with the authenticated user’s company, filtered by tags, categories, source names, and last call statuses.

​
Endpoint Details

  • URL: /contact/query
  • Method: GET
  • Authentication: Required (API KEY)

​
Request Headers

HeaderValueDescription
AuthorizationBearer <api_key>Your API KEY

​
Body Details

FieldTypeDescriptionExample
tagsArray of strings (optional)Filter contacts by their associated tags. When not provided, contacts with any tags will be included in the results.["important", "follow-up"]
categoriesArray of strings (optional)Filter contacts by their assigned categories. If omitted, contacts from all categories will be included.["lead", "customer"]
source_namesArray of strings (optional)Filter contacts by their acquisition source. When not specified, contacts from all sources will be returned.["website", "referral"]
last_call_statusesArray of strings (optional)Filter contacts by the status of their most recent call. If not provided, contacts with any call status will be included.["completed", "no-answer"]

​
Example Request

    ​
    Response

    ​
    Success Response

    • Status Code: 200 OK
    {
  "status": "ok",
  "message": "ok",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "company_id": "550e8400-e29b-41d4-a716-446655440000",
      "firstname": "John",
      "lastname": "Doe",
      "phone_number": "+1234567890",
      "metadata": {
        "custom_field": "value"
      },
      "number_country_code": "+1",
      "last_call_status": "answered",
      "last_call_at": "2023-10-01T12:00:00Z",
      "last_call_duration": 120,
      "last_call_feedback": "Positive",
      "source_name": "web",
      "tag_name": "vip",
      "category_name": "sales",
      "notes": "Important client",
      "created_at": "2023-10-01T12:00:00Z",
      "updated_at": "2023-10-01T12:00:00Z",
      "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active"
    }
  ]
}

    ​
    Error Response

    • Status Code: 200 OK (with error message)
    When an error occurs in your endpoint, the server responds with an HTTP status code of 200 OK. However, the response body contains an error message in a structured format to indicate that something went wrong. This approach is sometimes used to standardize API responses, even for errors. 
    {
  "status": "error",
  "message": "error",
  "data": ""
}

    ​
    Response Fields

    The data object represents a contact and has the following structure:
    FieldTypeDescription
    idstringThe unique identifier for the contact (UUID).
    company_idstringThe unique identifier for the company associated with the contact(UUID).
    firstnamestringThe first name of the contact.
    lastnamestringThe last name of the contact.
    phone_numberstringThe phone number of the contact.
    metadataobjectAdditional metadata associated with the contact.
    number_country_codestringThe country code for the phone number.
    last_call_status stringThe status of the last call made to the contact (e.g., busy, unreachable, in-progress, picked-up, no-answer).
    last_call_atstringThe timestamp of the last call made to the contact.
    last_call_durationintegerThe duration of the last call in seconds.
    last_call_feedbackstringFeedback from the last call.
    tag_namestringThe tag associated with the contact.
    category_namestringThe category associated with the contact.
    notesstringAdditional notes or description for the contact.
    created_atstringTimestamp when the campaign was created.
    updated_atstringTimestamp when the campaign was last updated.
    campaign_idstringThe unique identifier for the campaign associated with the contact.
    statusstringThe current status of the contact (e.g., active, inactive).