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

# Create a customer

`POST /customers`

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.

## Request body

- object
  - `address` object — Customer's address.
    - `city` string — City.
    - `country` string — 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` string — Primary address line.
    - `line2` string — Secondary address line.
    - `postal_code` string — Postal or ZIP code.
    - `state` string — State or region.
  - `email` string — Customer's email. At least one of `email` or `tax_id` is required.
  - `metadata` object — Set of key-value pairs that you can attach to an object. Useful for storing additional information about the object in a structured format.
  - `name` string — Customer's full name or business name.
  - `phone` string — Customer's phone number in E.164 format, including the country code (for example `+56911111111`).
  - `tax_id` object — Tax identifier (Chilean RUT or Mexican RFC). At least one of `email` or `tax_id` is required.
    - `type` 'cl_rut' | 'mx_rfc', required — Country-specific tax identifier format. One of `cl_rut` for Chilean tax ID (RUT) or `mx_rfc` for Mexican tax ID (RFC).
    - `value` string, required — 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).

## Response `201`

Customer created.

- Customer
  - `id` string, required — Unique identifier of the customer.
  - `object` 'customer', required — Type of the object. Always `customer`.
  - `address` object, nullable, required — Customer's address. Only the fields with a value are returned. `null` when the customer has no address information.
    - `city` string — City.
    - `country` string — Two-letter country code (ISO 3166-1 alpha-2), in lowercase.
    - `line1` string — Primary address line.
    - `line2` string — Secondary address line.
    - `postal_code` string — Postal or ZIP code.
    - `state` string — State or region.
  - `created_at` string, date-time, required — ISO 8601 datetime, in UTC, of when the customer was created.
  - `email` string, nullable, required — Customer's email, stored in lowercase. `null` if not provided.
  - `metadata` object, required — Set of key-value pairs that you can attach to an object. Useful for storing additional information about the object in a structured format.
  - `mode` 'live' | 'test', required — Mode of the customer, matching the mode of the API key used to create it. One of `live` or `test`.
  - `name` string, nullable, required — Customer's full name or business name. `null` if not provided.
  - `phone` string, nullable, required — Customer's phone number in E.164 format, including the country code (for example `+56911111111`). `null` if not provided.
  - `tax_id` object, nullable, required — Tax identifier of the customer (Chilean RUT or Mexican RFC). `null` if not provided.
    - `type` 'cl_rut' | 'mx_rfc', required — Type of tax identifier. One of `cl_rut` (Chilean RUT) or `mx_rfc` (Mexican RFC).
    - `value` string, required — Value of the tax identifier, normalized. RUTs are stored without dots or hyphens, and RFCs are stored in uppercase.

## Other responses

- `400` — 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.
- `401` — Invalid or missing API key.
- `409` — A customer with the same `tax_id` already exists in the mode of the API key used.

---

[API](https://skmtc.net/fintoc/apis/fintoc-api.md) · [All operations](https://skmtc.net/fintoc/apis/fintoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fintoc/fintoc-api/revisions/9dafa63688a3/schema)