---
title: "Create customer"
method: POST
path: "/customers"
tags: ["Customers"]
---

# Create customer

`POST /customers`

Creates a new customer (buyer or seller). If a customer with the same email/phone already exists
for this account, the existing record is updated and returned.

Either `email` or `phone` (with `prefix`) is required.

## Request body

- object
  - `name` string
  - `first_name` string
  - `last_name` string
  - `email` string, email — Required if `phone` is not provided.
  - `prefix` string — Phone country prefix (e.g. `+34`). Required with `phone`.
  - `phone` string — Phone number without prefix. Required if `email` is not provided.
  - `locale` string — Customer's preferred locale.
  - `tag` string — Custom tag for grouping or filtering.
  - `vat_id` string — Tax identification number.
  - `type` 'CLEARJUNCTION' | 'CURRENCYCLOUD' — Gateway-linked customer type. When set, additional KYC fields become required. `CLEARJUNCTION` requires id card fields; `CURRENCYCLOUD` also requires email and phone.
  - `metadata` object — Arbitrary key-value metadata. For `CLEARJUNCTION` and `CURRENCYCLOUD` types, pass KYC data under `metadata.kyc`.
    - `kyc` object — KYC identity data. Required for CLEARJUNCTION / CURRENCYCLOUD.
      - `date_birth` string, date — Date of birth. Required for CLEARJUNCTION / CURRENCYCLOUD.
      - `type` 'company' | 'individual' — Entity type. Required for CURRENCYCLOUD.
      - `street_residence` string — Street address. Required for CLEARJUNCTION / CURRENCYCLOUD.
      - `city_residence` string — City. Required for CLEARJUNCTION / CURRENCYCLOUD.
      - `zip_residence` string — Postal code. Required for CLEARJUNCTION.
      - `country_residence` string — 2-letter country code. Required for CLEARJUNCTION / CURRENCYCLOUD.
      - `id_card_type` string — ID document type. Required for CLEARJUNCTION.
      - `id_card` string — ID document number. Required for CLEARJUNCTION.
      - `id_card_country` string — 2-letter country code of the ID. Required for CLEARJUNCTION.

## Response `200`

Customer created or updated

- Customer
  - `id` integer
  - `self` string
  - `uuid` string
  - `type` string, nullable
  - `name` string, nullable
  - `first_name` string, nullable
  - `last_name` string, nullable
  - `email` string, email, nullable
  - `prefix` string, nullable
  - `phone` string, nullable
  - `tag` string, nullable
  - `metadata` object, nullable
  - `created_at` string, date-time, nullable
  - `connections` Connections — Hypermedia links to related resources.

## Other responses

- `422` — Validation error

## Changes

- **2026-03-24** `33c8b5a6215c` — 3 info
  - added the new optional request property `metadata/kyc`
  - added the new optional request property `type`
  - added the new optional request property `vat_id`

[Change history](https://skmtc.dev/truust-io/apis/truust-api/changes/customers/post.md)

---

[API](https://skmtc.dev/truust-io/apis/truust-api.md) · [All operations](https://skmtc.dev/truust-io/apis/truust-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/truust-io/truust-api/revisions/cc81e28726b9/schema)