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_KEYwithbusiness:customers:create,business:properties:createandbusiness:accounts:create. Addbusiness:customers:readandbusiness:accounts:readfor the checks. A restricted key (prefixsk_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.
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"}'
{
"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".
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#
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"}'
{
"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:
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.