# Create a new customer

Create a new customer to send or request funds.

Endpoint: POST /payments/br/customers/
Version: 1.223.0
Security: basicAuth

## Header parameters:

  - `X-Belvo-API-Resource-Version` (string)
    Header indicating which version of the Payment API you want to use. Currently this is only applicable for Bank Accounts, Customers, and Payment Authorizations in Brazil. In the case that you are using our Payment Authorizations product, then you must send through this header set to Payments-BR.V2.

{% admonition type="warning" name="Coming Soon" %}
  This version is in Coming Soon. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
    Enum: "Payments-BR.V2"

## Request fields (application/json):

  - `body` (object) — one of:
    - V2 - Create Customer:
      - `identifier` (string, required)
        The CPF (11 digits) or CNPJ (14 digits) of the customer.
        Example: "12345678901122"
      - `name` (string, required)
        The full name or business name of the customer.
        Example: "Frangos Enlatados"
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
    - V1 - Create Customer:
      - `identifier` (string, required)
        The customer's CPF or CNPJ number.
        Example: "10187609363"
      - `name` (string)
        The full name of the customer you want to create.
        Example: "Gustavo Veloso"
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `email` (string)
        The customer's email address.
        Example: "gustavo.veloso@musicabrazil.br"
      - `phone` (string,null)
        The customer's phone number.
        Example: "+5511987654321"
      - `address` (string,null)
        The customer's physical address.
        Example: "Rua de Gustavo Veloso 432, 70200 Brasilia"

## Response 201 fields (application/json):

  - `body` (object) — one of:
    - V2 - Customer:
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `created_at` (string, required)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `updated_at` (string, required)
        The ISO-8601 timestamp of when the data point was updated in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `name` (string, required)
        The full name or business name of the customer.
        Example: "Frangos Enlatados"
      - `identifier` (string, required)
        The CPF (11 digits) or CNPJ (14 digits) of the customer.
        Example: "12345678901122"
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
    - V1 - Customer:
      - `id` (string, required)
        Belvo's unique identifier for the current item.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `created_at` (string, required)
        The ISO-8601 timestamp of when the data point was created in Belvo's database.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_by` (string, required)
        The unique ID for the user that created this item.
        Example: "bcef7f35-67f2-4b19-b009-cb38795faf09"
      - `customer_type` (string, required)
        The type of customer. Can be either:

  - INDIVIDUAL
  - BUSINESS (Brazil OFPI only)
        Enum: "INDIVIDUAL", "BUSINESS"
      - `name` (string,null, required)
        The full name of the customer.
        Example: "Gustavo Veloso"
      - `external_id` (string)
        An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
        Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"
      - `country` (string,null, required)
        The customer's country of residence.
-  BRA (🇧🇷 Brazil)
        Enum: "BRA", "null"
      - `email` (string,null, required)
        The customer's email address.
        Example: "gustavo.veloso@musicabrazil.br"
      - `identifier` (string, required)
        The document number of the customer's ID (depending on the identifier_type).
        Example: "00000000000191"
      - `identifier_type` (string, required)
        The customer's ID document type. For Brazil, this can be either:

- CPF (when customer_type is INDIVIDUAL)
- CNPJ (when customer_type is BUSINESS)
        Enum: "CPF", "CNPJ"
      - `address` (string,null)
        The customers physical address.
        Example: "Rua de Gustavo Veloso 432, 70200 Brasilia"
      - `phone` (string,null)
        The customer's phone number.
        Example: "+5511987654321"

## Response 400 fields (application/json):

  - `code` (string, required)
    A unique error code (null, does_not_exist, required, already_registered, invalid_choice, max_length, min_length, blank, null, cancellation_error, idempotency_key_invalid) that allows you to classify and handle the error programmatically.
    Example: "required"

  - `message` (string, required)
    A short description of the error.


The description can be (among others):

  - This field is required.
  - Object with name=narnia does not exist.
  - This field may not be null.
  - This field may not be blank.
  - This customer is already registered
  - Ensure this field has at least 2 characters.
  - Ensure this field has no more than 4 characters.
  - Entered value is not valid.
  - You must set all required fields: username, password, username_type.
  - Payment Intent cannot be canceled because it is not SCHEDULED.
  - Payment Intent cannot be canceled as the cutoff time (23:59:00) has passed.
  - The provided idempotency key is invalid.
    Example: "This field is required."

  - `request_id` (string, required)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `field` (string,null)
    Name of the field where the error was encountered.

> Note: This field is only present when the error is related to a specific field.
    Example: "institution"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"