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

# Contacts

> The reusable debtor: centralizes the data of whoever pays so you can reuse it across multiple charges.

A **contact** (`Contact`) represents the **debtor**: the person or entity you charge. It centralizes their data (name, email, phones) so you can reuse it in future charges without repeating the information.

**When to create it explicitly:** when you want to maintain a debtor roster or reuse the same one across multiple charges. If you only charge once, creating it inline when creating the [debt](/en/resources/debts) is enough.

## Natural key: `externalClientId`

The `externalClientId` is the contact's natural key and is **unique per organization**. It is the value you use to reference the debtor in debts and subscriptions. The `contactId` (with the `con_` prefix) is the identifier that TapiPay assigns.

## Create a contact

`externalClientId`, `name`, and `email` are required.

```bash theme={null}
curl --request POST \
  --url 'https://tapipay-facade.dev.tapila.cloud/contacts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalClientId": "CLI-00042",
    "name": "Sample Customer",
    "email": "cliente@example.com",
    "phones": [
      { "number": "+5215512345678", "type": "MOBILE", "primary": true }
    ]
  }'
```

```json theme={null}
{
  "data": {
    "contactId": "con_9aL3kP2m",
    "externalClientId": "CLI-00042",
    "name": "Sample Customer",
    "email": "cliente@example.com",
    "phones": [
      { "number": "+5215512345678", "type": "MOBILE", "primary": true, "description": null }
    ],
    "active": true,
    "createdAt": "2026-06-03T18:05:00Z",
    "updatedAt": "2026-06-03T18:05:00Z"
  },
  "requestId": "req_a1b2c3d4"
}
```

<Note>
  Creating a contact with an `externalClientId` that already exists returns `409 RESOURCE_CONFLICT`.
</Note>

### Phones

Each phone has a required `number` and `type`, and optional `primary` and `description`. The `type` must be one of:

`MAIN`, `MOBILE`, `WORK`, `RELATIVE`, `OTHER`.

A `type` outside that list returns `400 INVALID_REQUEST`.

## Use the contact in a charge

In a debt or subscription, you identify the debtor in **one** of these two ways (exactly one):

<CardGroup cols={2}>
  <Card title="By reference" icon="link">
    You send the `externalClientId` of an existing contact. If it does not exist, it returns `422 BUSINESS_RULE_VIOLATION`.
  </Card>

  <Card title="Inline" icon="user-plus">
    You send `contactData` with the complete data. If the `externalClientId` does not exist, it is created; if it already exists, it is updated.
  </Card>
</CardGroup>

In the charge response, the contact comes embedded with three fields:

```json theme={null}
{
  "contact": {
    "contactId": "con_9aL3kP2m",
    "externalClientId": "CLI-00042",
    "createdInline": true
  }
}
```

`createdInline` is `true` if the contact was created in that request, and `false` if it already existed (was reused or updated).

## Update

`PATCH /contacts/{id}` updates `name`, `email`, or `phones` (at least one). The `externalClientId` is **not modifiable**. When you update `phones`, the list you send completely replaces the previous one.

<Note>
  The contact has no `metadata` or delete operation (`DELETE`) in v1. Manage its lifecycle with `PATCH`.
</Note>

## Endpoints

| Method  | Path             | Description                                                                          |
| ------- | ---------------- | ------------------------------------------------------------------------------------ |
| `POST`  | `/contacts`      | Create a contact.                                                                    |
| `GET`   | `/contacts/{id}` | Retrieve a contact.                                                                  |
| `GET`   | `/contacts`      | List contacts (filters `name`, `email`, `phone`, `externalClientId`, `contactCode`). |
| `PATCH` | `/contacts/{id}` | Update `name`, `email`, or `phones`.                                                 |

<Card title="Try it in the API Reference" icon="play" href="/api-reference">
  Explore each endpoint with its interactive playground.
</Card>