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.homo.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": "MOBILE" }
    ],
    "active": true,
    "createdAt": "2026-06-03T18:05:00.000Z",
    "updatedAt": "2026-06-03T18:05:00.000Z"
  },
  "requestId": "req_a1b2c3d4"
}

Creating a contact with an externalClientId that already exists returns 409 RESOURCE_CONFLICT. Fields not declared in the body are ignored.

Phones

Each phone has a required number and type, and optional primary and description. If you do not send description, it takes the value of type (for example, "MOBILE"). 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).

Search contacts

GET /contacts accepts these filters, which can be combined:

Filter	Behavior
`name`	Partial match on name.
`email`	Exact email.
`phone`	Phone number.
`contactCode`	Public ID of the contact, with or without the `con_` prefix. Exact match.
`identifier`	Searches by any identifier of the contact: its `externalClientId` or a secondary one (for example, a cash reference). Exact match.
`externalClientId`	Same filter as `identifier`. If you send both with different values, the API answers `400 INVALID_REQUEST`.

Pagination uses page (default 1) and limit (default 50, maximum 500). See API conventions.

Update

PATCH /contacts/{id} updates name, email, or phones. Rules:

Send at least one of name, email, or phones: an empty body returns 400 INVALID_REQUEST.
The externalClientId is not modifiable: sending it, or any other unlisted field, returns 400.
The email cannot be removed: "email": null returns 400.
phones replaces the whole list. An empty list ("phones": []) returns 400; to keep the current phones, omit the field.
The companyCode in the body is taken as company context, not as a field to modify.

curl --request PATCH \
  --url 'https://tapipay-facade.homo.tapila.cloud/contacts/con_9aL3kP2m' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "phones": [
      { "number": "+5215587654321", "type": "WORK", "primary": true }
    ]
  }'

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

Errors

Besides validation errors (400) and authentication errors (see Authentication), the contact endpoints can answer:

Situation	Response
Duplicate `externalClientId` on create	`409 RESOURCE_CONFLICT`
A business rule is violated on create	`422 BUSINESS_RULE_VIOLATION`
`companyCode` that does not belong to your client	`422 RESOLUTION_ERROR`
The contact was created but could not be read back	`422 RESOLUTION_ERROR` (the contact exists: look it up with `GET /contacts?externalClientId=`)
The contacts service fails while listing	`500 INTERNAL_ERROR`

Endpoints

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

Try it in the API Reference

Explore each endpoint with its interactive playground.

Get started

What's new

Concepts

Resources

Payment portal

Webhooks

Natural key: `externalClientId`

Create a contact

Phones

Use the contact in a charge

By reference

Inline

Search contacts

Update

Errors

Endpoints

Try it in the API Reference

​Natural key: externalClientId

​Create a contact

​Phones

​Use the contact in a charge

By reference

Inline

​Search contacts

​Update

​Errors

​Endpoints

Try it in the API Reference

Natural key: `externalClientId`

Create a contact

Phones

Use the contact in a charge

Search contacts

Update

Errors

Endpoints