> ## Documentation Index > Fetch the complete documentation index at: https://docs.truust.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Customer > 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. ## OpenAPI ````yaml POST /customers openapi: 3.1.0 info: title: Truust API version: '2.0' description: > The Truust API allows you to manage payment flows, orders, customers, wallets, and more. ## Authentication All authenticated endpoints require a Bearer token using your account's **Secret Key**. ``` Authorization: Bearer {your_secret_key} ``` Your API keys are available in the Dashboard under **Account Settings → API Developers**. contact: email: hello@truust.io license: name: Proprietary servers: - url: https://{subdomain}.truust.io/2.0 description: Production variables: subdomain: default: your-subdomain description: Your account subdomain - url: https://{subdomain}-sandbox.truust.io/2.0 description: Sandbox variables: subdomain: default: your-subdomain description: Your account subdomain security: - bearerAuth: [] tags: - name: Account description: Manage your Truust account - name: Customers description: Manage buyers and sellers (end users) - name: Orders description: Create and manage escrow payment orders - name: Payins description: Manage incoming payments for orders - name: Payouts description: Manage outgoing payments from orders - name: Wallets description: Manage customer and account wallets - name: Bank Accounts description: Manage bank accounts for payouts - name: Cards description: Manage tokenized payment cards - name: Subscriptions description: Manage recurring payment subscriptions - name: Verifications description: KYC verification for customers and accounts - name: Bundles description: Manage product bundles for orders - name: Refunds description: View refund records paths: /customers: post: tags: - Customers summary: Create customer description: > 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. operationId: createCustomer requestBody: required: true content: application/json: schema: type: object example: name: John Doe email: john@example.com prefix: '+34' phone: '612345678' properties: name: type: string maxLength: 255 example: John Doe first_name: type: string maxLength: 255 example: John last_name: type: string maxLength: 255 example: Doe email: type: string format: email maxLength: 255 description: Required if `phone` is not provided. example: john@example.com prefix: type: string description: Phone country prefix (e.g. `+34`). Required with `phone`. example: '+34' phone: type: string description: >- Phone number without prefix. Required if `email` is not provided. example: '612345678' locale: type: string description: Customer's preferred locale. example: es tag: type: string maxLength: 100 description: Custom tag for grouping or filtering. vat_id: type: string maxLength: 255 description: Tax identification number. type: type: string enum: - CLEARJUNCTION - CURRENCYCLOUD description: > Gateway-linked customer type. When set, additional KYC fields become required. `CLEARJUNCTION` requires id card fields; `CURRENCYCLOUD` also requires email and phone. metadata: type: object additionalProperties: true description: > Arbitrary key-value metadata. For `CLEARJUNCTION` and `CURRENCYCLOUD` types, pass KYC data under `metadata.kyc`. properties: kyc: type: object description: >- KYC identity data. Required for CLEARJUNCTION / CURRENCYCLOUD. properties: date_birth: type: string format: date description: >- Date of birth. Required for CLEARJUNCTION / CURRENCYCLOUD. type: type: string enum: - company - individual description: Entity type. Required for CURRENCYCLOUD. street_residence: type: string description: >- Street address. Required for CLEARJUNCTION / CURRENCYCLOUD. city_residence: type: string description: City. Required for CLEARJUNCTION / CURRENCYCLOUD. zip_residence: type: string description: Postal code. Required for CLEARJUNCTION. country_residence: type: string description: >- 2-letter country code. Required for CLEARJUNCTION / CURRENCYCLOUD. id_card_type: type: string description: ID document type. Required for CLEARJUNCTION. id_card: type: string description: ID document number. Required for CLEARJUNCTION. id_card_country: type: string description: >- 2-letter country code of the ID. Required for CLEARJUNCTION. responses: '200': description: Customer created or updated content: application/json: schema: $ref: '#/components/schemas/Customer' '422': $ref: '#/components/responses/ValidationError' components: schemas: Customer: type: object properties: id: type: integer self: type: string example: /2.0/customers/abc123 uuid: type: string type: type: string nullable: true name: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true email: type: string format: email nullable: true prefix: type: string nullable: true example: '+34' phone: type: string nullable: true tag: type: string nullable: true metadata: type: object nullable: true additionalProperties: true created_at: type: string format: date-time nullable: true connections: $ref: '#/components/schemas/Connections' Connections: type: object description: Hypermedia links to related resources. additionalProperties: type: string responses: ValidationError: description: Validation error content: application/json: schema: type: object properties: message: type: string example: The given data was invalid. errors: type: object additionalProperties: type: array items: type: string example: name: - The name field is required. securitySchemes: bearerAuth: type: http scheme: bearer description: Use your account's **Secret Key** as the Bearer token. ````