Skip to main content

Retrieve Contact by Phone Number

Retrieve a single contact by their phone number.

The number you pass is normalized to E.164 before the lookup, so any format that resolves to the same number works — +1 (415) 555-0123 and +14155550123 match the same contact. Numbers without a leading + are interpreted using the default region configured on the workspace phone_number field.

Endpoint​

GET https://api.campaignlark.com/v1/contacts/by-phone

Query Parameters​

ParameterTypeRequiredDescription
phone_numberstringrequiredThe phone number of the contact to retrieve.

Sample Request​

GET https://api.campaignlark.com/v1/contacts/by-phone?phone_number=%2B14155550123

Response​

Success — 200 OK​

{
  "data": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "status": "SUBSCRIBED",
    "score": 0,
    "tags": [
      { "id": 1, "name": "newsletter" }
    ],
    "fields": {
      "email_address": "joffrey@example.com",
      "first_name": "Joffrey Baratheon",
      "phone_number": "+14155550123"
    },
    "sms_status": "SUBSCRIBED",
    "last_opened_at": "2024-02-14T09:00:00Z",
    "last_clicked_at": null,
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-02-14T09:00:00Z"
  }
}

Contact responses include sms_status. If no SMS status is stored, sms_status is reported as SUBSCRIBED.

Errors​

StatusMessageCause
400Phone number is required. Please provide a valid phone number.phone_number query parameter is missing.
400Phone number is invalid. Please provide a valid phone number.The number could not be parsed, or it has no country code and the workspace phone_number field has no default region.
404We couldn't find a contact with that phone number.No contact with that phone number exists in the workspace, or the workspace has no phone_number field configured.