# 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"
}
```

✓ Checkpoint: the status code is `201`, `status` is `active` and `id` starts with `cus_`. Keep that `id` for the next two steps.

## 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}'
```

✓ Checkpoint: `201` with an `id` that starts with `prp_`, the same `customer_id` and `status: "active"`. The API records this first ownership as a transfer to the customer, so the property's history starts on the day you import it.

## 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"
}
```

✓ Checkpoint: `201` with `status: "active"` and an `account_number` from the utility's gap-free series. Residents type that number to link the account in their app. A property owned by a different customer returns `409`; an unknown customer or property returns `404`.

## 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"
```

✓ Checkpoint: `data` lists the matches and `has_more` says whether another page exists.

## 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

- [Record the first meter readings for the new accounts](/docs/guides/record-readings)
- [Issue a manual invoice or a credit note on an account](/docs/guides/issue-invoices)
- [Give the import job a restricted key with only these scopes](/docs/getting-started/restricted-keys)
- [How Idempotency-Key replays and conflicts work](/docs/getting-started/idempotency)

