Import customers

Move a customer register into the API as customers, properties and service accounts, in the order the API needs, with idempotency keys that make a second run safe.

What you will build#

A script that turns one row of your existing customer register into three linked records: the customer (who pays), the property (the premises where water is supplied) and the service account (the record that meters, invoices and payments attach to). Creating a customer does not create a property or an account, so an import that stops after the first call leaves customers nobody can bill. Every request carries an Idempotency-Key built from the row's own ID, which means you can run the whole import again after a failure without creating duplicates.

Prerequisites#

  • A sandbox. It already holds sample customers, so lists return more than the rows you import here.
  • A test API key in $API_KEY with business:customers:create, business:properties:create and business:accounts:create. Add business:customers:read and business:accounts:read for the checks. A restricted key (prefix sk_rtest_) with exactly these scopes is the safest choice for an import job.
  • A stable ID for each source row. This guide uses ROW-0042.

1. Create the customer#

display_name, customer_type (individual or business) and category (residential, commercial, industrial, institutional or government) are required. tax_number, email and phone are optional, and the API trims them before storing. The body is decoded strictly, so an unknown field such as name is refused with 400.

bash
curl -sS -X POST "$BUSINESS_API/customers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: import-ROW-0042-customer" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Ana Macuácua","customer_type":"individual","category":"residential","phone":"+258841234567"}'
json
{
  "id": "cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Macuácua",
  "phone": "+258841234567",
  "status": "active",
  "created_at": "2026-11-19T09:14:03Z",
  "updated_at": "2026-11-19T09:14:03Z"
}

2. Register the property#

customer_id and address_line are required. latitude and longitude go together or not at all. If you send service_area_id, it must name one of the utility's own service areas; any other value returns 400 with error_code: "validation.invalid_choice".

bash
curl -sS -X POST "$BUSINESS_API/properties" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: import-ROW-0042-property" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7","address_line":"Rua da Resistência, 1147","locality":"Malhangalene","district":"KaMpfumo","province":"Maputo Cidade","premise_type":"residential","latitude":-25.9553,"longitude":32.5892}'

3. Open the service account#

bash
curl -sS -X POST "$BUSINESS_API/accounts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: import-ROW-0042-account" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7","property_id":"prp_2pN4wA3cHs7QkV1yMd5TnJ8eXb2"}'
json
{
  "id": "act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "customer_id": "cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7",
  "property_id": "prp_2pN4wA3cHs7QkV1yMd5TnJ8eXb2",
  "account_number": "CTA-000318",
  "billing_entity_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "status": "active",
  "opened_at": "2026-11-19T09:14:05Z"
}

4. Run it again safely#

Repeat any call with the same key and the same body and the API returns the stored response with the header Idempotent-Replayed: true. The same key with a different body returns 409 with error_code: "request.idempotency_conflict". Keys are kept for 24 hours, so an import resumed later should first look for the customer:

bash
curl -sS "$BUSINESS_API/customers?q=Macu%C3%A1cua&category=residential&limit=5" \
  -H "Authorization: Bearer $API_KEY"

Test it#

From the command line, gotactl customers get cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7 --json id,display_name,status shows the customer and gotactl accounts list --customer-id cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7 --json id,account_number,status shows the account. In the dashboard, the customer appears under Customers and the property with its account under Properties and accounts.

Next steps#