Clients

Create, list, and manage debtor clients via the ezpays API.

Clients represent the debtors you are recovering from. Each client is uniquely identified within your tenant by a tax_id (VAT / fiscal ID) or an external_debtor_id (your own internal identifier).

Create or resolve a client

POST /v1/clients is an upsert operation: if a client with the supplied tax_id or external_debtor_id already exists, it is returned; otherwise a new client is created.

All POST endpoints require an Idempotency-Key header (see the Idempotency guide).

Required fields

At least one identity field must be present:

The name field is also required.

Optional fields

Example request

curl https://api.ezpays.app/api/public/v1/clients \
  -H "Authorization: Bearer ezp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "tax_id": "B12345678",
    "email": "billing@acme.example",
    "phone": "+34 912 345 678"
  }'

Example response — 201 Created

{
  "id": "dbr_a1b2c3...",
  "external_debtor_id": null,
  "name": "Acme Corporation",
  "email": "billing@acme.example",
  "phone": "+34 912 345 678",
  "tax_id": "B12345678",
  "address": null
}

When the client already exists (matched by tax_id or external_debtor_id), the non-identity fields (name, email, phone, address) are automatically refreshed with the values you supply. This ensures repeat imports or updates keep contact details current without creating duplicates.

List clients

GET /v1/clients returns a paginated list of all clients in your tenant.

Query parameters

Example request

curl "https://api.ezpays.app/api/public/v1/clients?status=active&limit=10" \
  -H "Authorization: Bearer ezp_test_..."

Example response — 200 OK

{
  "data": [
    {
      "id": "dbr_a1b2c3...",
      "external_debtor_id": null,
      "name": "Acme Corporation",
      "email": "billing@acme.example",
      "phone": "+34 912 345 678",
      "tax_id": "B12345678",
      "address": null
    }
  ],
  "page": {
    "has_more": false,
    "next_cursor": null
  }
}

Retrieve a client

GET /v1/clients/{id} returns a single client by its internal id.

curl "https://api.ezpays.app/api/public/v1/clients/dbr_a1b2c3..." \
  -H "Authorization: Bearer ezp_test_..."

Returns 404 if the client does not exist or belongs to a different tenant.

Identity model

Two fields serve as the deduplication identity for a client:

1. external_debtor_id — checked first. Use this if you have your own stable customer identifier (e.g. CRM ID). This is the preferred key for bulk imports.
2. tax_id — fallback deduplication key. Used when no external_debtor_id is provided, or for manual client creation.

If both are supplied, external_debtor_id takes priority for lookup. The stored client will have both values recorded.

Scopes

See the Authentication guide for details on API keys and scopes.