iotoms Docs

Create a customer

POST
/api/v1/crm/customers

Creates a customer profile. Email and first name are required, and email and mobile number must not already belong to another customer. The customer number (e.g. CUS-000-2026-00042) is assigned by the system and returned in the response with status 201.

How to use it

  1. Send at least email and firstName, plus any contact, address and category details.
  2. The customer number is generated and returned; use it for Get, Update, Partially update and Delete a customer and on carts.
  3. Add India GST details afterwards with Partially update a customer.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
id?|

Internal numeric ID. Set by the server. Customers are addressed by customerNumber in URLs, not by this ID.

Formatint64
email*string

Customer's email address. Required, must be a valid email and unique across customers.

mobileNumber?|

Mobile number, up to 20 characters. Must be unique across customers when set.

Length0 <= length <= 20
countryCode?|

Dialling or country code that goes with the phone numbers, up to 10 characters, e.g. +971.

Length0 <= length <= 10
landPhoneNumber?|

Landline number, up to 20 characters.

Length0 <= length <= 20
firstName*string

First name. Required, up to 255 characters.

Length0 <= length <= 255
lastName?|

Last name, up to 255 characters.

Length0 <= length <= 255
city?|

City of the customer's address.

Length0 <= length <= 255
state?|

State, province or emirate of the customer's address, as free text.

Length0 <= length <= 255
country?|

Country of the customer's address, as free text.

Length0 <= length <= 255
zipCode?|

Postal or ZIP code, up to 20 characters.

Length0 <= length <= 20
profileImageUrl?|

URL of the customer's photo or avatar, up to 1024 characters.

Length0 <= length <= 1024
status*string

ACTIVE, INACTIVE, ARCHIVED or DELETED. Defaults to ACTIVE. List customers returns only ACTIVE by default when any filter is used.

Value in"ACTIVE""INACTIVE""ARCHIVED""DELETED"
dob?|

Date of birth, YYYY-MM-DD.

Formatdate
category?|

Merchant-defined customer group, e.g. "Wholesale", up to 64 characters. Filterable by exact match.

Length0 <= length <= 64
modifiedTime*string

When the profile was last changed, ISO 8601 date-time. Defaults to the current time if not sent.

Formatdate-time
createdTime*string

When the profile was created, ISO 8601 date-time. Defaults to the current time if not sent.

Formatdate-time

Response Body

OK

*/*
  1. response
id?|

Internal numeric ID. Set by the server. Customers are addressed by customerNumber in URLs, not by this ID.

Formatint64
customerNumber*string

Unique customer number, e.g. CUS-000-2026-00042. Set by the server on create; used in the URL of every single-customer call.

email*string

Customer's email address. Required, must be a valid email and unique across customers.

mobileNumber?|

Mobile number, up to 20 characters. Must be unique across customers when set.

countryCode?|

Dialling or country code that goes with the phone numbers, up to 10 characters, e.g. +971.

landPhoneNumber?|

Landline number, up to 20 characters.

firstName*string

First name. Required, up to 255 characters.

lastName?|

Last name, up to 255 characters.

city?|

City of the customer's address.

state?|

State, province or emirate of the customer's address, as free text.

country?|

Country of the customer's address, as free text.

zipCode?|

Postal or ZIP code, up to 20 characters.

profileImageUrl?|

URL of the customer's photo or avatar, up to 1024 characters.

status*string

ACTIVE, INACTIVE, ARCHIVED or DELETED. Defaults to ACTIVE. List customers returns only ACTIVE by default when any filter is used.

Value in"ACTIVE""INACTIVE""ARCHIVED""DELETED"
dob?|

Date of birth, YYYY-MM-DD.

Formatdate
category?|

Merchant-defined customer group, e.g. "Wholesale", up to 64 characters. Filterable by exact match.

modifiedTime*string

When the profile was last changed, ISO 8601 date-time. Defaults to the current time if not sent.

Formatdate-time
createdTime*string

When the profile was created, ISO 8601 date-time. Defaults to the current time if not sent.

Formatdate-time
gstin?|

India: the customer's 15-character GST identification number. Set via Partially update a customer.

panNumber?|

India: the customer's 10-character PAN (tax ID).

gstRegistrationType?|

India: GST status - REGULAR, COMPOSITION, UNREGISTERED, CONSUMER (B2C), SEZ or OVERSEAS. Null means not stated. Set via Partially update a customer.

Value in"REGULAR""COMPOSITION""UNREGISTERED""CONSUMER""SEZ""OVERSEAS"null
gstStateCode?|

India: two-character GST state code of the buyer, used to work out the place of supply.

vatRegistrationNumber?|

The customer's VAT registration number, up to 20 characters; shown on VAT reports and the EC Sales List.

vatCountryCode?|

Two-letter country code of the customer's VAT registration, e.g. DE.

euVatValidated*boolean

true when the customer's EU VAT number has been validated. Only validated customers appear on the EC Sales List.

euVatExempt*boolean

Marks the customer as exempt from EU VAT. Stored for reference only; it does not currently change how VAT is charged or reported.

taxExemptionNumber?|

US: sales-tax exemption certificate number, shown on Americas tax reports.

taxExemptionState?|

US: state that issued the tax exemption certificate.

rfcNumber?|

Mexico: the customer's RFC tax ID, up to 13 characters.

createdViaAi*boolean

true when the customer was created through the AI assistant or an AI data import. Set by the server.

aiSessionId?|

ID of the AI assistant or AI import session that created or last changed the customer, if any. Set by the server.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/crm/customers' \  -H 'Content-Type: application/json' \  -d '{  "email": "string",  "firstName": "string",  "status": "ACTIVE",  "modifiedTime": "2019-08-24T14:15:22Z",  "createdTime": "2019-08-24T14:15:22Z"}'
Example Response
{  "id": 0,  "customerNumber": "string",  "email": "string",  "mobileNumber": "string",  "countryCode": "string",  "landPhoneNumber": "string",  "firstName": "string",  "lastName": "string",  "city": "string",  "state": "string",  "country": "string",  "zipCode": "string",  "profileImageUrl": "string",  "status": "ACTIVE",  "dob": "2019-08-24",  "category": "string",  "modifiedTime": "2019-08-24T14:15:22Z",  "createdTime": "2019-08-24T14:15:22Z",  "gstin": "string",  "panNumber": "string",  "gstRegistrationType": "REGULAR",  "gstStateCode": "string",  "vatRegistrationNumber": "string",  "vatCountryCode": "string",  "euVatValidated": true,  "euVatExempt": true,  "taxExemptionNumber": "string",  "taxExemptionState": "string",  "rfcNumber": "string",  "createdViaAi": true,  "aiSessionId": "string"}