iotoms Docs

Sync customers

Keep customer records in step with your system. Look a customer up, create them if they are new, update them, and pull the records that changed since your last sync.

Customers in iotoms are identified by a customer number that iotoms assigns, for example CUS-000-2026-00042. Sales can carry it, so purchases are linked to the customer. This guide shows a two-way sync: push your customers into iotoms without creating duplicates, and pull back the ones that changed.

At the end you will have each of your customers matched to an iotoms customer number, and a repeatable way to fetch recent changes.

Before you start you need a token and the merchant's tenant code. See Authentication.

These endpoints skip the envelope

The customer endpoints return the record (or the page of records) directly, not inside data.

Step 1 — Look the customer up

Search first so you do not create a second record for someone who is already there.

curl 'https://beta.iotoms.com/api/v1/crm/customers?email=asha.menon@example.com&page=0&size=20' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>'
  • email matches any address that contains the text, ignoring case. Compare the email of each result with yours before treating it as a match.
  • mobileNumber and customerNumber must match exactly.
  • When you filter, only ACTIVE customers are returned unless you also pass status. You can repeat it, for example status=ACTIVE&status=INACTIVE.

Results are in content. Paging details are in page (number, size, totalElements and totalPages). If you find a match, keep its customerNumber and go to Step 3.

Endpoint: List customers

Step 2 — Create the customer

If nothing matched, create the customer. iotoms gives them their customer number.

curl -X POST 'https://beta.iotoms.com/api/v1/crm/customers' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "asha.menon@example.com",
    "firstName": "Asha",
    "lastName": "Menon",
    "mobileNumber": "501234567",
    "countryCode": "+971",
    "city": "Dubai",
    "country": "United Arab Emirates",
    "category": "Wholesale",
    "status": "ACTIVE"
  }'
  • email and firstName are required, and email must be a valid address.
  • Do not send createdTime or modifiedTime. iotoms sets both to the current time.
  • Field limits: mobileNumber and landPhoneNumber up to 20 characters, countryCode up to 10, zipCode up to 20.
  • email and mobileNumber must each be unique. A duplicate returns 409. Go back to Step 1 and match on that field.

The response (201) is the new customer. Store customerNumber against your own record. It is the ID in every customer URL, and it is what you send with a sale.

Endpoint: Create a customer

Step 3 — Update the customer

Choose a full replace when your system owns the whole record, or a partial update when it only owns a few fields.

Full replace. Send the complete record. Any field you leave out is cleared, and a missing status goes back to ACTIVE.

curl -X PUT 'https://beta.iotoms.com/api/v1/crm/customers/CUS-000-2026-00042' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "asha.menon@example.com",
    "firstName": "Asha",
    "lastName": "Menon",
    "mobileNumber": "501234567",
    "countryCode": "+971",
    "city": "Abu Dhabi",
    "country": "United Arab Emirates",
    "category": "Wholesale",
    "status": "ACTIVE"
  }'

Partial update. Send only the fields that changed. iotoms ignores any field name it does not recognise.

curl -X PATCH 'https://beta.iotoms.com/api/v1/crm/customers/CUS-000-2026-00042' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "city": "Abu Dhabi"
  }'

Both return the updated customer. An unknown customer number returns 404.

Only a full replace moves the modified time

A full replace sets modifiedTime to now, as long as you do not send modifiedTime in the body. A partial update leaves it unchanged. If you rely on Step 4 to pick up changes, change customers with the full replace and leave modifiedTime out.

Endpoints: Update a customer · Partially update a customer

Step 4 — Pull changes since your last sync

Fetch only the customers whose record changed since a point in time, a page at a time.

curl 'https://beta.iotoms.com/api/v1/crm/customers?updatedFrom=2026-10-17T00:00:00Z&status=ACTIVE&status=INACTIVE&page=0&size=100' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>'
  • updatedFrom and updatedTo filter on the customer's modifiedTime. Send a full date and time with a time zone. Both limits are inclusive.
  • createdFrom and createdTo do the same for new customers.
  • Use updatedFrom. The updatedSince parameter is not applied to customers.
  • size can be up to 100. Increase page until page.number + 1 equals page.totalPages.

Save the time you started the run, and use it as updatedFrom next time.

Endpoint: List customers

Step 5 — Link sales to the customer

Put the customer number on a sale so the purchase shows in that customer's history and reports.

Send customerNumber on both the cart and the transaction when you record a sale. To read one customer back at any time, use Get a customer.

What's next

Record a sale

Ring up a sale for the customer you just synced.

Requests, responses and errors

Error codes and paging rules used across the API.

On this page

Step 1 — Look the customer upStep 2 — Create the customerStep 3 — Update the customerStep 4 — Pull changes since your last syncStep 5 — Link sales to the customerWhat's next