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.