> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Contact

> Retrieve detailed contact information and list memberships by phone number.

Returns contact details and all list memberships for a given phone number across every sending list owned by your account. This provides a unified view of a contact's carrier information, validation status, and per-list engagement metrics.

## Path Parameters

<ParamField path="phone_number" type="string" required>
  Contact phone number in E.164 format. Must be URL-encoded in the request path (e.g., `%2B14155559876` for `+14155559876`).
</ParamField>

## Response Fields

<ResponseField name="phone_number" type="string">
  Contact phone number in E.164 format.
</ResponseField>

<ResponseField name="carrier" type="string">
  Mobile carrier name (e.g., `T-Mobile`, `Verizon`, `AT&T`). `null` when the number has never been validated for your account.
</ResponseField>

<ResponseField name="line_type" type="string">
  Phone line type. Values: `mobile`, `landline`, `voip`, `toll_free`, `unknown`, `premium_rate`. `null` when the number has never been validated for your account, when the number carries no classification, or when flagged as an invalid number (a `fake`/invalid-number verdict stores `line_type: null` and sets `is_valid` to `false`).
</ResponseField>

<ResponseField name="timezone" type="string">
  Contact's timezone based on phone number area code (e.g., `America/New_York`).
</ResponseField>

<ResponseField name="is_valid" type="boolean">
  Whether the phone number passed carrier validation and is deliverable. `null` if the number has never been validated for your account.
</ResponseField>

<ResponseField name="country" type="string">
  ISO 3166-1 alpha-2 country code. `null` if the number has never been validated for your account.
</ResponseField>

<ResponseField name="lists" type="array">
  Array of list membership objects representing every list this contact appears on within your account.

  <Expandable title="List membership properties">
    <ResponseField name="list_id" type="integer">
      Unique identifier of the sending list.
    </ResponseField>

    <ResponseField name="list_number" type="string">
      Sending list phone number in E.164 format.
    </ResponseField>

    <ResponseField name="active" type="boolean">
      Whether the contact is currently subscribed to this list.
    </ResponseField>

    <ResponseField name="signup_date" type="string">
      ISO 8601 UTC timestamp of when the contact was added to this list.
    </ResponseField>

    <ResponseField name="unsub_reason" type="string">
      Reason for the most recent unsubscribe on this list (e.g., `message`, `bad_response`, `invalid_contact`, `manual`, `complaint`, `api` (set by the Delete Contact endpoint), or a `replied stop ...` string when the contact texted a STOP keyword). `null` if the contact has never unsubscribed or has since resubscribed.
    </ResponseField>

    <ResponseField name="unsub_date" type="string">
      ISO 8601 UTC timestamp of the most recent unsubscribe on this list. `null` if the contact has never unsubscribed or has since resubscribed.
    </ResponseField>

    <ResponseField name="custom_fields" type="object">
      Key-value pairs of custom fields for this contact on this list.
    </ResponseField>

    <ResponseField name="send_count" type="integer">
      Total messages sent to this contact on this list.
    </ResponseField>

    <ResponseField name="click_count" type="integer">
      Total link clicks from this contact on this list.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tracklysms.com/api/v2/contacts/%2B14155559876" \
    -H "X-Api-Key: trk_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests
  from urllib.parse import quote

  phone_number = "+14155559876"
  encoded_phone = quote(phone_number, safe="")

  response = requests.get(
      f"https://api.tracklysms.com/api/v2/contacts/{encoded_phone}",
      headers={"X-Api-Key": "trk_your_api_key_here"}
  )

  data = response.json()
  print(f"Phone: {data['phone_number']}")
  print(f"Carrier: {data['carrier']}")
  print(f"Lists: {len(data['lists'])}")

  for membership in data["lists"]:
      print(f"  {membership['list_number']} - Active: {membership['active']}")
  ```

  ```javascript Node.js theme={null}
  const phoneNumber = "+14155559876";
  const encodedPhone = encodeURIComponent(phoneNumber);

  const response = await fetch(
    `https://api.tracklysms.com/api/v2/contacts/${encodedPhone}`,
    {
      method: "GET",
      headers: {
        "X-Api-Key": "trk_your_api_key_here",
      },
    }
  );

  const data = await response.json();
  console.log(`Phone: ${data.phone_number}`);
  console.log(`Carrier: ${data.carrier}`);
  console.log(`On ${data.lists.length} list(s)`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "phone_number": "+14155559876",
    "carrier": "T-Mobile",
    "line_type": "mobile",
    "timezone": "America/Los_Angeles",
    "is_valid": true,
    "country": "US",
    "lists": [
      {
        "list_id": 42,
        "list_number": "+18005551234",
        "active": true,
        "signup_date": "2025-03-15T14:30:00",
        "unsub_reason": null,
        "unsub_date": null,
        "custom_fields": {
          "first_name": "Jane",
          "source": "landing_page_v2"
        },
        "send_count": 12,
        "click_count": 3
      },
      {
        "list_id": 43,
        "list_number": "+18005559999",
        "active": false,
        "signup_date": "2025-01-10T09:00:00",
        "unsub_reason": "message",
        "unsub_date": "2025-02-01T11:15:00",
        "custom_fields": {},
        "send_count": 5,
        "click_count": 0
      }
    ]
  }
  ```

  ```json 400 - Invalid Phone Number theme={null}
  {
    "error": "Invalid E.164 phone number format",
    "code": "invalid_phone"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "error": "Contact not found",
    "code": "not_found"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code            | Description                                                                     |
| ----------- | --------------------- | ------------------------------------------------------------------------------- |
| 400         | `invalid_phone`       | The phone number in the path is not a valid E.164 number.                       |
| 401         | `invalid_credentials` | Missing or invalid `X-Api-Key` header.                                          |
| 403         | `account_suspended`   | Your account is suspended. Resolve outstanding billing or contact support.      |
| 429         | `rate_limited`        | Request throttled; retry with exponential backoff after the window resets.      |
| 404         | `not_found`           | The contact does not exist or is not on any sending list owned by your account. |
| 500         | `internal_error`      | An unexpected server error occurred.                                            |

<Note>
  The `+` character in E.164 phone numbers must be URL-encoded as `%2B` in the path. For example, `+14155559876` becomes `%2B14155559876`.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Importing Contacts" icon="upload" href="/guides/contacts/importing">
    Import contacts in bulk
  </Card>

  <Card title="Create Audience" icon="users" href="/api-reference/v2/audiences/create-audience">
    Segment your contacts
  </Card>
</CardGroup>