---
updatedAt: 2026-06-03T12:16:05.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# Create new customer

Endpoint responsible for registering a new customer in the Asaas account.

This registration serves as the foundation for subsequent integration operations, such as creating charges, subscriptions, and other flows that require a previously identified payer.

After creation, the API returns the customer's unique identifier in Asaas, which must be stored by the application for use in subsequent requests.

***

## Main request parameters

Some fields play an important role in the integration behavior:

* `name` — Customer name displayed in the record
* `cpfCnpj` — Customer document number (a common criterion for duplicate validation)
* `mobilePhone` and `email` — Contact details used for communication and notifications
* `externalReference` — Customer identifier in the source system (highly recommended)
* `notificationDisabled` — Defines whether the customer will receive notifications
* `additionalEmails` — Additional recipients for notifications
* `groupName` — Allows logical grouping of customers
* `foreignCustomer` — Must be set to `true` for foreign customers

***

## Identifier returned upon creation

The API response returns the customer's unique identifier in Asaas.

This identifier must be stored by the application, as it will be used in operations such as:

* charge creation
* subscription creation
* customer record updates
* individual customer retrieval
* notification retrieval

Although the customer's document number can be used in searches, the Asaas identifier is the most reliable value for relating entities within the API.

***

## How customer creation works

This endpoint is responsible for registering the payer that will be used in subsequent integration operations.

After creation, the API returns the customer's unique identifier in Asaas, which must be stored by the application for use in subsequent requests.

Since the API allows duplicate customer creation, integrations that require unique customer records must implement prior validation, usually based on `cpfCnpj`, `externalReference`, or reuse of an identifier already stored internally.

***

> 🚧 Attention
>
> The API allows duplicate customer creation.
> It is the integration's responsibility to implement duplicate prevention strategies before creating a customer.

***

## Duplicate prevention strategy

The most common strategies are:

* search in advance by `cpfCnpj`
* validate by `externalReference`
* store the ID of the previously created customer internally and reuse it

This validation is especially important in scenarios involving:

* event reprocessing
* asynchronous queues
* automatic customer creation attempts

***

## Recommended use of `externalReference`

Whenever possible, it is recommended to send the `externalReference` field.

This attribute makes reconciliation between systems easier, reduces dependence on searches by name or document number, and helps prevent duplicate creation.

In more robust integrations, this field is usually the link between the source system identifier and the customer record stored in Asaas.

***

## Address behavior when providing a ZIP code

When the request includes `postalCode`, Asaas may automatically fill in address information based on the ZIP code provided.

In this scenario, the integration flow can be simplified, reducing the need to manually fill in additional address attributes.

Even so, the address number (`addressNumber`) remains a relevant piece of information.

***

## Foreign customers

Foreign customer registration depends on the environment and the account permissions.

* In production, this feature must be enabled
* In sandbox, it can be used without prior enablement

***

> ❗️ Attention
>
> For integrations that operate with international payers, make sure to verify in advance whether the production account has this permission enabled before putting the flow into operation.

***

## Considerations for the sandbox environment

Email and SMS notifications work normally in sandbox.

***

> ❗️ Attention
>
> Avoid using real third-party data during testing, as the environment may trigger actual communications.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Asaas",
    "description": "API pública de integração com a plataforma Asaas.",
    "version": "3.0.0"
  },
  "servers": [
    {
      "url": "https://api-sandbox.asaas.com",
      "description": "Sandbox"
    }
  ],
  "security": [
    {
      "Authorization": []
    }
  ],
  "tags": [
    {
      "name": "Customer"
    }
  ],
  "paths": {
    "/v3/customers": {
      "post": {
        "tags": [
          "Customer"
        ],
        "summary": "Create new customer",
        "description": "",
        "operationId": "create-new-customer",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerSaveRequestDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerGetResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDTO"
                },
                "example": {
                  "errors": [
                    {
                      "code": "error_code",
                      "description": "Error description"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseDTO"
                },
                "example": {
                  "errors": [
                    {
                      "code": "invalid_access_token",
                      "description": "A chave de API fornecida é inválida"
                    }
                  ]
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponseDTO": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "List of objects",
            "deprecated": false,
            "items": {
              "$ref": "#/components/schemas/ErrorResponseItemDTO"
            }
          }
        }
      },
      "ErrorResponseItemDTO": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "deprecated": false,
            "example": null
          },
          "description": {
            "type": "string",
            "description": "Error description",
            "deprecated": false,
            "example": null
          }
        },
        "description": "List of objects",
        "deprecated": false
      },
      "CustomerGetResponseDTO": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "description": "Object type",
            "example": "customer",
            "deprecated": false
          },
          "id": {
            "type": "string",
            "description": "Unique customer identifier",
            "example": "cus_000005401844",
            "deprecated": false
          },
          "dateCreated": {
            "type": "string",
            "description": "Customer creation date",
            "example": "2024-07-12",
            "deprecated": false
          },
          "name": {
            "type": "string",
            "description": "Client name",
            "example": "John Doe",
            "deprecated": false
          },
          "email": {
            "type": "string",
            "description": "Customer email",
            "example": "john.doe@asaas.com.br",
            "deprecated": false
          },
          "phone": {
            "type": "string",
            "description": "Customer phone",
            "example": "90999999999",
            "deprecated": false
          },
          "mobilePhone": {
            "type": "string",
            "description": "Customer cell phone",
            "example": "90999999999",
            "deprecated": false
          },
          "address": {
            "type": "string",
            "description": "Customer address",
            "example": "Av. Paulista",
            "deprecated": false
          },
          "addressNumber": {
            "type": "string",
            "description": "Customer address number",
            "example": "150",
            "deprecated": false
          },
          "complement": {
            "type": "string",
            "description": "Customer address complement",
            "example": "Sala 201",
            "deprecated": false
          },
          "province": {
            "type": "string",
            "description": "Customer address neighborhood",
            "example": "Centro",
            "deprecated": false
          },
          "city": {
            "type": "integer",
            "description": "Unique city identifier in Asaas",
            "format": "int32",
            "example": 12565,
            "deprecated": false
          },
          "cityName": {
            "type": "string",
            "description": "City of customer address",
            "example": "São Paulo",
            "deprecated": false
          },
          "state": {
            "type": "string",
            "description": "Customer address status",
            "example": "SP",
            "deprecated": false
          },
          "country": {
            "type": "string",
            "description": "Customer country",
            "example": "Brasil",
            "deprecated": false
          },
          "postalCode": {
            "type": "string",
            "description": "Customer address zip code",
            "example": "01310000",
            "deprecated": false
          },
          "cpfCnpj": {
            "type": "string",
            "description": "Customer CPF or CNPJ",
            "example": "24971563792",
            "deprecated": false
          },
          "personType": {
            "$ref": "#/components/schemas/CustomerGetResponsePersonType"
          },
          "deleted": {
            "type": "boolean",
            "description": "Indicates whether it is a deleted client",
            "example": false,
            "deprecated": false
          },
          "additionalEmails": {
            "type": "string",
            "description": "Additional customer emails",
            "example": "john.doe@asaas.com,john.doe.silva@asaas.com.br",
            "deprecated": false
          },
          "externalReference": {
            "type": "string",
            "description": "External customer reference",
            "example": "12987382",
            "deprecated": false
          },
          "notificationDisabled": {
            "type": "boolean",
            "description": "Indicates whether notifications are disabled",
            "example": false,
            "deprecated": false
          },
          "observations": {
            "type": "string",
            "description": "Customer Observations",
            "example": "great payer, no problems so far",
            "deprecated": false
          },
          "foreignCustomer": {
            "type": "boolean",
            "description": "Indicates if it's non-brazilian customer",
            "example": false,
            "deprecated": false
          }
        }
      },
      "CustomerGetResponsePersonType": {
        "type": "string",
        "description": "Kind of person",
        "example": "FISICA",
        "deprecated": false,
        "enum": [
          "JURIDICA",
          "FISICA"
        ]
      },
      "CustomerSaveRequestDTO": {
        "required": [
          "name",
          "cpfCnpj"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Client name",
            "nullable": false,
            "example": "John Doe",
            "deprecated": false
          },
          "cpfCnpj": {
            "type": "string",
            "description": "Customer CPF or CNPJ",
            "nullable": false,
            "example": "24971563792",
            "deprecated": false
          },
          "email": {
            "type": "string",
            "description": "Customer email",
            "example": "john.doe@asaas.com.br",
            "deprecated": false
          },
          "phone": {
            "type": "string",
            "description": "Landline",
            "example": "4738010919",
            "deprecated": false
          },
          "mobilePhone": {
            "type": "string",
            "description": "Cell phone",
            "example": "4799376637",
            "deprecated": false
          },
          "address": {
            "type": "string",
            "description": "Public place",
            "example": "Av. Paulista",
            "deprecated": false
          },
          "addressNumber": {
            "type": "string",
            "description": "Address number",
            "example": "150",
            "deprecated": false
          },
          "complement": {
            "type": "string",
            "description": "Address complement (max. 255 characters)",
            "example": "Sala 201",
            "deprecated": false
          },
          "province": {
            "type": "string",
            "description": "Neighborhood",
            "example": "Centro",
            "deprecated": false
          },
          "postalCode": {
            "type": "string",
            "description": "Address zip code",
            "example": "01310-000",
            "deprecated": false
          },
          "externalReference": {
            "type": "string",
            "description": "Customer identifier in your system",
            "example": "12987382",
            "deprecated": false
          },
          "notificationDisabled": {
            "type": "boolean",
            "description": "true to disable sending billing notifications",
            "example": false,
            "deprecated": false
          },
          "additionalEmails": {
            "type": "string",
            "description": "Additional emails for sending billing notifications separated by \",\"",
            "example": "john.doe@asaas.com,john.doe.silva@asaas.com.br",
            "deprecated": false
          },
          "municipalInscription": {
            "type": "string",
            "description": "Customer municipal registration",
            "example": "46683695908",
            "deprecated": false
          },
          "stateInscription": {
            "type": "string",
            "description": "Customer state registration",
            "example": "646681195275",
            "deprecated": false
          },
          "observations": {
            "type": "string",
            "description": "Additional observations",
            "example": "great payer, no problems so far",
            "deprecated": false
          },
          "groupName": {
            "type": "string",
            "description": "Name of the group the customer belongs to. To associate the customer with more than one group, use the \"groupNames\" attribute",
            "deprecated": false,
            "example": null
          },
          "groupNames": {
            "type": "array",
            "description": "List of names of the groups the customer belongs to (maximum of 20 per call). Can be used together with \"groupName\"",
            "example": [
              "Grupo A",
              "Grupo B"
            ],
            "deprecated": false,
            "items": {
              "type": "string",
              "description": "List of names of the groups the customer belongs to (maximum of 20 per call). Can be used together with \"groupName\"",
              "example": [
                "Grupo A",
                "Grupo B"
              ],
              "deprecated": false
            }
          },
          "company": {
            "type": "string",
            "description": "Company",
            "deprecated": false,
            "example": null
          },
          "foreignCustomer": {
            "type": "boolean",
            "description": "inform true if it's a non-brazilian customer",
            "example": false,
            "deprecated": false
          }
        }
      }
    },
    "securitySchemes": {
      "Authorization": {
        "type": "apiKey",
        "name": "access_token",
        "in": "header"
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "key": "User-Agent",
        "value": "NomeDaSuaAplicacao/1.0.0"
      }
    ]
  }
}
```

# Sibling pages

* [List customers](https://docs.asaas.com/reference/list-customers.md)
* [Retrieve a single customer](https://docs.asaas.com/reference/retrieve-a-single-customer.md)
* [Update existing customer](https://docs.asaas.com/reference/update-existing-customer.md)
* [Remove Customer](https://docs.asaas.com/reference/remove-customer.md)
* [Restore removed customer](https://docs.asaas.com/reference/restore-removed-customer.md)
* [Retrieve notifications from a customer](https://docs.asaas.com/reference/retrieve-notifications-from-a-customer.md)