API reference · Customers · Customer Management

Create New Customer

Method: POST
Route: /v1/customer
Base URL: https://ws.autorei.net
Token: Requires Bearer token

Opens this request in the public API documentation, the official source of the reference.

Description

Registers a customer in your store, with the address and, optionally, the customer type, group and price tag links. The customer created can already access the store with the username and password provided.

Request body (JSON)

Field	Type	Required	Description
`documentType`	string	Yes	`cpf` or `pf` for an individual; `cnpj` or `pj` for a legal entity. No other value is accepted.
`document`	string	Yes	CPF or CNPJ, valid and consistent with the `documentType`. Alphanumeric CNPJ is accepted.
`username`	string	Yes	Customer login e-mail. Must be a valid e-mail.
`phone`	string	Yes	Customer phone number.
`password`	string	Yes	Customer login password.
`customerRegistrationAddress`	object	Conditional	Customer registration address. Fields are in the address table. See the rule below.
`addressList`	array	Conditional	Customer delivery addresses. Fields are in the address table. See the rule below.
`name`	string	No	Name or legal name.
`tradingName`	string	No	Trade name.
`contactName`	string	No	Contact name.
`stateRegistration`	string	No	State registration.
`cnae`	string	No	Customer CNAE.
`paysIcms`	boolean	No	Whether the customer is an ICMS taxpayer.
`politicallyExposedPerson`	boolean	No	Whether the customer is a politically exposed person.
`federalEmployee`	boolean	No	Whether the customer is a federal employee.
`optinTracking`	boolean	No	Opt-in to tracking by message.
`trackingPhone`	string	No	Tracking phone number.
`forceChangePassword`	boolean	No	Requires a password change on first access.
`passwordExpired`	boolean	No	Marks the password as expired. When absent, it defaults to `false`.
`sendEmailNewCustomer`	boolean	No	`true` triggers the first-access e-mail to the customer. The password you sent is never included in that e-mail.
`ssoConfigId`	integer	No	SSO configuration. Validated against your store.
`priceRuleTags`	array	No	Price tags, by name.
`customerTypeList`	array	No	Customer types, by `name` or `externalId`.
`customerGroupList`	array	No	Customer groups, by `name` or `externalId`.

Address (customerRegistrationAddress and each item of addressList):

Field	Type	Required	Description
`zipcode`	string	Yes	Address ZIP code (CEP). It is what resolves street and neighborhood — see the Correios rule.
`number`	string	Yes	Number.
`complement`	string	No	Complement.
`street`	string	Conditional	Street. See the Correios rule.
`quarter`	string	Conditional	Neighborhood. See the Correios rule.
`city`	string	No	City.
`state`	string	No	State (UF).
`addressType`	string	No	`RESIDENTIAL` or `BUSINESS`. Case-insensitive.
`farmerStateRegistration`	string	No	Farmer state registration.
`principal`	boolean	No	Marks the address as the main one.
`name`	string	No	Address name.
`lat` · `lng`	number	No	Coordinates. Only accepted if your store has the latitude/longitude feature enabled.

Business rules

`customerRegistrationAddress` and `addressList` store different things

Both are addresses, but they go to different places and sending only one has different effects:

What you send	What the customer gets
Only `customerRegistrationAddress`	Registration address filled in, and no delivery address — the list stays empty.
Only `addressList`, with one item `principal: true`	The delivery addresses from the list, and the registration address copied from the main item.
Both	The delivery addresses from the list and the registration address you provided.
Only `addressList` with no `principal: true`	Rejected — there is no registration address to determine.
Neither	Rejected.

The rejection is Property [address] with value [] does not pass validation.

The ZIP code (CEP) rules the address

The address is resolved by Correios from the zipcode, and what Correios returns replaces what you sent in street, quarter, city and state. Only number and complement survive from your payload — which Correios does not have.

The fields you send work as a fallback: each one is used only when Correios does not return that data for the ZIP code (CEP). After the merge, street and quarter cannot be empty — if they are, creation is rejected.

A ZIP code (CEP) not found is also rejected, unless your store has ZIP code validation disabled.

An invalid `addressType` is not rejected

A value other than RESIDENTIAL/BUSINESS falls back to the default RESIDENTIAL, with no error.

Response · 200

The customer created, at the root (without the customer envelope). The code is 200, not 201.

Field	Type	Description
`id`	integer	Customer id in CWS.
`document`	string	Customer CPF or CNPJ.
`documentType`	string	`pf` or `pj`.
`name`	string	Name or legal name.
`tradingName`	string	Trade name.
`contactName`	string	Contact name.
`email`	string	Customer login e-mail.
`phone`	string	Phone number, already formatted (`(31) 99999-9999`).
`dateCreated`	string	Registration date and time.
`active`	boolean	Whether the customer is active.
`passwordExpired`	boolean	Whether the password is marked as expired.
`stateRegistration`	string	State registration. Comes as `"isento"` when not provided.
`cnae`	string	Customer CNAE.
`paysIcms`	boolean	Whether the customer is an ICMS taxpayer.
`genre`	string	Gender.
`birthdate`	string	Date of birth.
`politicallyExposedPerson`	boolean	Whether the customer is a politically exposed person.
`federalEmployee`	boolean	Whether the customer is a federal employee.
`optinTracking`	boolean	Whether the customer accepts tracking by message.
`trackingPhone`	string	Tracking phone number.
`optinPath`	string	Origin of the consent.
`address`	array	Customer addresses, in the same format as `GET /customer/addresses/:document`.
`customerRegistrationAddress`	object	Registration address.
`priceRuleTag`	array	Customer price tags. Comes as `null` when there is no link.
`customerTypeList`	array	Linked customer types. `null` when there is no link.
`customerGroupList`	array	Linked customer groups. `null` when there is no link.

Errors

Code	When
422	Validation failure: `{"status":"UNPROCESSABLE_ENTITY","message":"Property [campo] with value [x] does not pass validation"}`. The message names the rejected field — `documentType`, `username`, `document`, `phone`, `password`, `ssoConfigId` or `address`.
401	Token missing, malformed or expired.
400	Body cannot be parsed, or e-mail or document already registered in your store.
401	Token missing, malformed or expired.

Example request

curl --request POST 'https://ws.autorei.net/v1/customer' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "documentType": "cpf",
  "document": "70041364856",
  "username": "ana.ribeiro@exemplo.com.br",
  "name": "Ana Paula Ribeiro",
  "contactName": "Ana Paula Ribeiro",
  "phone": "11987654321",
  "password": "sua-senha",
  "optinTracking": true,
  "trackingPhone": "11987654321",
  "customerRegistrationAddress": {
    "zipcode": "01310-100",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 42",
    "quarter": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "addressType": "RESIDENTIAL",
    "principal": true
  }
}'

Example responses

200Success — individual

{
  "id": 4470601,
  "document": "700.413.648-56",
  "documentType": "pf",
  "name": "Ana Paula Ribeiro",
  "tradingName": null,
  "contactName": "Ana Paula Ribeiro",
  "email": "ana.ribeiro@exemplo.com.br",
  "phone": "(11) 98765-4321",
  "dateCreated": "2026-09-01T13:42:07Z",
  "active": true,
  "passwordExpired": false,
  "stateRegistration": "isento",
  "cnae": null,
  "paysIcms": false,
  "genre": "F",
  "birthdate": "1988-04-12",
  "politicallyExposedPerson": false,
  "federalEmployee": false,
  "optinTracking": true,
  "trackingPhone": "(11) 98765-4321",
  "optinPath": "API",
  "address": [
    {
      "id": 4470701,
      "name": "Endereço de cadastro",
      "zipcode": "01310-100",
      "street": "Avenida Paulista",
      "number": "1578",
      "complement": "Conjunto 42",
      "quarter": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "principal": true,
      "addressType": "RESIDENTIAL",
      "farmerStateRegistration": null,
      "howToReachLocationDescription": null,
      "responsibleContact": null,
      "attributes": {},
      "dateCreated": "2026-09-01T13:42:07Z",
      "lastUpdated": "2026-09-01T13:42:07Z"
    }
  ],
  "customerRegistrationAddress": {
    "id": 4470701,
    "name": "Endereço de cadastro",
    "zipcode": "01310-100",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 42",
    "quarter": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "principal": true,
    "addressType": "RESIDENTIAL",
    "farmerStateRegistration": null,
    "howToReachLocationDescription": null,
    "responsibleContact": null,
    "attributes": {},
    "dateCreated": "2026-09-01T13:42:07Z",
    "lastUpdated": "2026-09-01T13:42:07Z"
  },
  "priceRuleTag": null,
  "customerTypeList": null,
  "customerGroupList": null
}

200Success — legal entity

{
  "id": 4470602,
  "document": "29.893.264/0001-01",
  "documentType": "pj",
  "name": "Comercial Aurora Ltda",
  "tradingName": "Aurora Distribuidora",
  "contactName": "Marcos Aurélio",
  "email": "compras@auroradistribuidora.com.br",
  "phone": "(11) 98765-4321",
  "dateCreated": "2026-09-01T13:42:07Z",
  "active": true,
  "passwordExpired": false,
  "stateRegistration": "123456789",
  "cnae": "4530703",
  "paysIcms": true,
  "genre": null,
  "birthdate": null,
  "politicallyExposedPerson": false,
  "federalEmployee": false,
  "optinTracking": true,
  "trackingPhone": "(11) 98765-4321",
  "optinPath": "API",
  "address": [
    {
      "id": 4470701,
      "name": "Endereço de cadastro",
      "zipcode": "01310-100",
      "street": "Avenida Paulista",
      "number": "1578",
      "complement": "Conjunto 42",
      "quarter": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "principal": true,
      "addressType": "RESIDENTIAL",
      "farmerStateRegistration": null,
      "howToReachLocationDescription": null,
      "responsibleContact": null,
      "attributes": {},
      "dateCreated": "2026-09-01T13:42:07Z",
      "lastUpdated": "2026-09-01T13:42:07Z"
    }
  ],
  "customerRegistrationAddress": {
    "id": 4470701,
    "name": "Endereço de cadastro",
    "zipcode": "01310-100",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 42",
    "quarter": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "principal": true,
    "addressType": "RESIDENTIAL",
    "farmerStateRegistration": null,
    "howToReachLocationDescription": null,
    "responsibleContact": null,
    "attributes": {},
    "dateCreated": "2026-09-01T13:42:07Z",
    "lastUpdated": "2026-09-01T13:42:07Z"
  },
  "priceRuleTag": null,
  "customerTypeList": null,
  "customerGroupList": null
}

Used in

Use casesEcommerce ERP integration: the typical path through the API
Use casesB2B customer portal: the typical path through the API
Use casesB2B marketplace: the typical path through the API
Use casesComplex retail and B2B2C: the typical path through the API
Use casesB2B procurement and supplies: the typical path through the API
Use casesGuided selling and counter sales: the typical path through the API
Webhooks and eventsCustomers webhook

GET Find Customer by Document /v1/customer/document/:document
PUT Update Customer Registration Data /v1/customer/:document
PUT Activate or Deactivate Customer /customer/updateStatus/:document/:active

← See the group: Customers

Generated from the public API collection, published on 2026-09-04: api-docs.cws.digital.