> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a customer

> Creates a customer in the `live` or `test` mode of the API key used. At least one of `email` or `tax_id` must be provided; every other field is optional. If a `tax_id` is provided, both its `type` and `value` are required. Values are normalized before being stored: `email` and `address.country` are lowercased, dots and hyphens are stripped from RUTs, and RFCs are uppercased.

**`v2`** · Base URL `https://api.fintoc.com/v2`


## OpenAPI

````yaml reference/fintoc-api-v2.json POST /customers
openapi: 3.1.0
info:
  title: fintoc-api-v2
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v2
security: []
paths:
  /customers:
    post:
      tags:
        - Customers
      summary: Create a customer
      description: >-
        Creates a customer in the `live` or `test` mode of the API key used. At
        least one of `email` or `tax_id` must be provided; every other field is
        optional. If a `tax_id` is provided, both its `type` and `value` are
        required. Values are normalized before being stored: `email` and
        `address.country` are lowercased, dots and hyphens are stripped from
        RUTs, and RFCs are uppercased.
      operationId: customers-create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: object
                  description: Customer's address.
                  properties:
                    city:
                      type: string
                      description: City.
                      example: Santiago
                    country:
                      type: string
                      example: CL
                      description: >-
                        Two-letter country code (ISO 3166-1 alpha-2),
                        case-insensitive. Must be a country Fintoc supports (see
                        https://docs.fintoc.com/docs/currencies).
                    line1:
                      type: string
                      description: Primary address line.
                      example: Av. Providencia 123
                    line2:
                      type: string
                      description: Secondary address line.
                      example: Depto 45
                    postal_code:
                      type: string
                      description: Postal or ZIP code.
                      example: '7500000'
                    state:
                      type: string
                      description: State or region.
                      example: RM
                email:
                  type: string
                  example: jared@piedpiper.com
                  description: >-
                    Customer's email. At least one of `email` or `tax_id` is
                    required.
                metadata:
                  type: object
                  description: >-
                    Set of key-value pairs that you can attach to an object.
                    Useful for storing additional information about the object
                    in a structured format.
                  example:
                    order_id: '12345'
                name:
                  type: string
                  example: Test Customer 1
                  description: Customer's full name or business name.
                phone:
                  type: string
                  example: '+56911111111'
                  description: >-
                    Customer's phone number in E.164 format, including the
                    country code (for example `+56911111111`).
                tax_id:
                  type: object
                  description: >-
                    Tax identifier (Chilean RUT or Mexican RFC). At least one of
                    `email` or `tax_id` is required.
                  properties:
                    type:
                      type: string
                      enum:
                        - cl_rut
                        - mx_rfc
                      description: >-
                        Country-specific tax identifier format. One of `cl_rut`
                        for Chilean tax ID (RUT) or `mx_rfc` for Mexican tax ID
                        (RFC).
                      example: cl_rut
                    value:
                      type: string
                      description: >-
                        Country-specific tax identification number. For
                        `cl_rut`, use a Chilean tax ID (RUT) with or without
                        dots and hyphens (for example `11.111.111-1` or
                        `111111111`). For `mx_rfc`, use a Mexican tax ID (RFC).
                      example: 11111111-1
                  required:
                    - type
                    - value
            examples:
              create_customer:
                summary: Create a customer
                value:
                  address:
                    city: Santiago
                    country: CL
                    line1: Av. Providencia 123
                    line2: Depto 45
                    postal_code: '7500000'
                    state: RM
                  email: jared@piedpiper.com
                  metadata:
                    order_id: '12345'
                  name: Test Customer 1
                  phone: '+56911111111'
                  tax_id:
                    type: cl_rut
                    value: 11111111-1
      responses:
        '201':
          description: Customer created.
          content:
            application/json:
              examples:
                customer_created:
                  value:
                    id: cus_0ujsswThIGTUYm2K8FjOOfXtY1K
                    object: customer
                    address:
                      city: Santiago
                      country: cl
                      line1: Av. Providencia 123
                      line2: Depto 45
                      postal_code: '7500000'
                      state: RM
                    created_at: '2026-01-15T14:30:00Z'
                    email: jared@piedpiper.com
                    metadata:
                      order_id: '12345'
                    mode: live
                    name: Test Customer 1
                    phone: '+56911111111'
                    tax_id:
                      type: cl_rut
                      value: '111111111'
              schema:
                $ref: '#/components/schemas/customer'
        '400':
          description: >-
            Invalid request: both `email` and `tax_id` are missing, the `email`
            is invalid, the `tax_id` is incomplete or invalid, the
            `address.country` is not supported, or the `metadata` has an invalid
            format.
          content:
            application/json:
              examples:
                missing_email_and_tax_id:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_parameter
                      param: email
                      message: either email or tax_id must be present
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
        '409':
          description: >-
            A customer with the same `tax_id` already exists in the mode of the
            API key used.
          content:
            application/json:
              examples:
                duplicate_tax_id:
                  value:
                    error:
                      type: conflicted_request_error
                      code: conflicted_request
                      message: A Customer with this tax_id already exists
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    customer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the customer.
          example: cus_0ujsswThIGTUYm2K8FjOOfXtY1K
        object:
          const: customer
          description: Type of the object. Always `customer`.
        address:
          type:
            - object
            - 'null'
          description: >-
            Customer's address. Only the fields with a value are returned.
            `null` when the customer has no address information.
          properties:
            city:
              type: string
              description: City.
              example: Santiago
            country:
              type: string
              description: Two-letter country code (ISO 3166-1 alpha-2), in lowercase.
              example: cl
            line1:
              type: string
              description: Primary address line.
              example: Av. Providencia 123
            line2:
              type: string
              description: Secondary address line.
              example: Depto 45
            postal_code:
              type: string
              description: Postal or ZIP code.
              example: '7500000'
            state:
              type: string
              description: State or region.
              example: RM
        created_at:
          type: string
          format: date-time
          description: ISO 8601 datetime, in UTC, of when the customer was created.
          example: '2026-01-15T14:30:00Z'
        email:
          type:
            - string
            - 'null'
          description: Customer's email, stored in lowercase. `null` if not provided.
          example: jared@piedpiper.com
        metadata:
          type: object
          description: >-
            Set of key-value pairs that you can attach to an object. Useful for
            storing additional information about the object in a structured
            format.
          example:
            order_id: '12345'
        mode:
          type: string
          enum:
            - live
            - test
          description: >-
            Mode of the customer, matching the mode of the API key used to
            create it. One of `live` or `test`.
          example: live
        name:
          type:
            - string
            - 'null'
          description: Customer's full name or business name. `null` if not provided.
          example: Test Customer 1
        phone:
          type:
            - string
            - 'null'
          description: >-
            Customer's phone number in E.164 format, including the country code
            (for example `+56911111111`). `null` if not provided.
          example: '+56911111111'
        tax_id:
          type:
            - object
            - 'null'
          description: >-
            Tax identifier of the customer (Chilean RUT or Mexican RFC). `null`
            if not provided.
          properties:
            type:
              type: string
              enum:
                - cl_rut
                - mx_rfc
              description: >-
                Type of tax identifier. One of `cl_rut` (Chilean RUT) or
                `mx_rfc` (Mexican RFC).
              example: cl_rut
            value:
              type: string
              description: >-
                Value of the tax identifier, normalized. RUTs are stored without
                dots or hyphens, and RFCs are stored in uppercase.
              example: '111111111'
          required:
            - type
            - value
      required:
        - id
        - object
        - address
        - created_at
        - email
        - metadata
        - mode
        - name
        - phone
        - tax_id
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````