Contacts

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

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 }
    ]
  }'

{
  "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"
}

Creating a contact with an externalClientId that already exists returns 409 RESOURCE_CONFLICT.

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):

By reference

You send the externalClientId of an existing contact. If it does not exist, it returns 422 BUSINESS_RULE_VIOLATION.

Inline

You send contactData with the complete data. If the externalClientId does not exist, it is created; if it already exists, it is updated.

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

{
  "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.

The contact has no metadata or delete operation (DELETE) in v1. Manage its lifecycle with PATCH.

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

Try it in the API Reference

Explore each endpoint with its interactive playground.

Get started

Concepts

Resources

Payment portal

Webhooks

Natural key: `externalClientId`

Create a contact

Phones

Use the contact in a charge

By reference

Inline

Update

Endpoints

Try it in the API Reference

​Natural key: externalClientId

​Create a contact

​Phones

​Use the contact in a charge

By reference

Inline

​Update

​Endpoints

Try it in the API Reference

Natural key: `externalClientId`

Create a contact

Phones

Use the contact in a charge

Update

Endpoints