> ## 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.

# Delete Contact

> Unsubscribe a contact from a sending list by setting their subscription status to inactive.

Unsubscribes a contact from the specified sending list. This sets the ListContact's active status to `false` with an unsubscribe reason of `api`. The contact record itself is **not deleted** -- only their subscription to the list is deactivated. This ensures historical data (send counts, click counts, revenue) is preserved for reporting.

The endpoint returns a success response even if the contact or list is not found. Check the `unsubscribed` field to determine whether an actual unsubscribe took place.

## Body Parameters

<ParamField body="phone_number" type="string" required>
  Contact phone number in E.164 format (e.g., `+14155559876`).
</ParamField>

<ParamField body="list_number" type="string" required>
  Sending list phone number in E.164 format (e.g., `+18005551234`). Must be a list owned by your account.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  Always `true` when the request is processed without error.
</ResponseField>

<ResponseField name="unsubscribed" type="boolean">
  `true` if the contact was found on the list (their status is set to inactive, even if they were already unsubscribed). `false` only if the contact does not exist, the list does not exist, or the contact is not a member of the list.
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.tracklysms.com/api/v2/contacts" \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "phone_number": "+14155559876",
      "list_number": "+18005551234"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      "https://api.tracklysms.com/api/v2/contacts",
      headers={
          "X-Api-Key": "trk_your_api_key_here",
          "Content-Type": "application/json"
      },
      json={
          "phone_number": "+14155559876",
          "list_number": "+18005551234"
      }
  )

  data = response.json()
  if data["unsubscribed"]:
      print("Contact was unsubscribed successfully")
  else:
      print("Contact was not found on the list (or already unsubscribed)")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.tracklysms.com/api/v2/contacts", {
    method: "DELETE",
    headers: {
      "X-Api-Key": "trk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: "+14155559876",
      list_number: "+18005551234",
    }),
  });

  const data = await response.json();
  console.log("Unsubscribed:", data.unsubscribed);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Contact unsubscribed theme={null}
  {
    "success": true,
    "unsubscribed": true
  }
  ```

  ```json 200 - Contact not found on list theme={null}
  {
    "success": true,
    "unsubscribed": false
  }
  ```

  ```json 400 - Missing required field theme={null}
  {
    "error": "phone_number is required",
    "code": "missing_phone_number"
  }
  ```

  ```json 400 - Invalid phone number theme={null}
  {
    "error": "Invalid E.164 phone number format",
    "code": "invalid_phone"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code             | Description                                                                |
| ----------- | ---------------------- | -------------------------------------------------------------------------- |
| 400         | `missing_phone_number` | The `phone_number` field was not provided in the request body.             |
| 400         | `missing_list_number`  | The `list_number` field was not provided in the request body.              |
| 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. |
| 400         | `invalid_phone`        | The `phone_number` is not a valid E.164 phone number.                      |
| 400         | `invalid_list_number`  | The `list_number` is not a valid E.164 phone number.                       |
| 500         | `internal_error`       | An unexpected server error occurred.                                       |

<Warning>
  This endpoint does **not** delete the contact record or their historical data. It only deactivates their subscription to the specified list. To fully remove a contact's data, use the account dashboard or contact support.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Importing Contacts" icon="upload" href="/guides/contacts/importing">
    Manage your contact data
  </Card>

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