Moving lots of customers at once

Sarah is moving off her old system. Three hundred customers in a spreadsheet, and she isn't adding them one at a time.

Bulk work doesn't happen while you wait. You start it, get a receipt, and check back. Same in both directions.

It's also the pattern for any long-running job elsewhere in the API, so it's worth reading once even if you never touch a spreadsheet.

Get the template first

curl https://api.hyphabase.com/api/modules/clients/import-export/template \
  -u sk_live_xxx: -H "X-Location-Id: $HYPHABASE_LOCATION_ID" \
  -o customers-template.csv

Comes back as CSV with the header row we expect. Build your file from this rather than guessing column names — the structure is checked before the job even starts, so a wrong header fails immediately instead of halfway through.

Send it in

Sent as multipart/form-data:

curl -X POST https://api.hyphabase.com/api/modules/clients/import-export/import \
  -u sk_live_xxx: \
  -H "X-Location-Id: $HYPHABASE_LOCATION_ID" \
  -F "file=@customers.csv" \
  -F "location_ids[]=$HYPHABASE_LOCATION_ID"

202 Accepted and a receipt:

{
  "data": {
    "id": "019fb0d4-8a21-70bb-9e12-4c8ab3e91f70",
    "type": "import",
    "status": "pending",
    "total_rows": 312,
    "original_filename": "customers.csv",
    "file_size": 38104
  }
}

202 means "we've taken it", not "it's done". Nothing exists yet.

Get data back out

JSON, and the filters mirror the normal list:

curl -X POST https://api.hyphabase.com/api/modules/clients/import-export/export \
  -u sk_live_xxx: -H "X-Location-Id: $HYPHABASE_LOCATION_ID" \
  -H "Content-Type: application/json" \
  -d '{"date_from":"2026-01-01","client_status_id":"'"$STATUS_ID"'"}'

Send {} for everything. total_rows on the receipt is how many matched, so you know the size before you wait for it.

Exporting is the right tool for taking a whole copy. Don't page the normal list three hundred times to build one — see Long lists.

Check back

status moves pending → processing → completed or failed.

async function waitForJob(jobId, { intervalMs = 2000, timeoutMs = 300_000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  for (;;) {
    const response = await fetch(
      `${BASE}/api/modules/clients/import-export/operations/${jobId}`,
      { credentials: 'include', headers: { 'X-Location-Id': locationId } },
    );
    const { data } = await response.json();

    onProgress(data.processed_rows ?? 0, data.total_rows);

    if (data.status === 'completed') return data;
    if (data.status === 'failed') throw new Error(data.error_message ?? 'Import failed');
    if (Date.now() > deadline) throw new Error('Timed out waiting for the import');

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
}

See everything with GET /api/modules/clients/import-export/operations, which is also how you find a job whose id you lost.

Download the export

Once it says completed:

curl https://api.hyphabase.com/api/modules/clients/import-export/operations/$JOB_ID/download \
  -u sk_live_xxx: -H "X-Location-Id: $HYPHABASE_LOCATION_ID" \
  -o customers-export.csv

Stopping and tidying up

Cancel something still running with POST /api/modules/clients/import-export/operations/{id}/cancel. Only pending and processing jobs can be cancelled.

Receipts pile up. Clear finished ones with DELETE /api/modules/clients/import-export/operations/clear, which removes completed and failed and leaves anything in flight alone.

Sarah's actual first import

That last step is not optional. Rows fail individually, and nothing tells you unless you look.

Next