Imports and exports

Check a batch of customers without importing it

Scopecustomers:write

Requires customers:write. Changes nothing and needs no Idempotency-Key. Answers, for each rowRef, whether the row is well formed (valid), which fields were refused (fields, names only) and whether the customer id is already a member of the program (alreadyMember, so importing it would be a no-op).

Path

iduuidRequired

Body

branchIduuid

The branch the customers join at; omitted, the program's own or first open one.

rowsobject[]Required

rows[].rowRefstringRequired

Your own reference for this row; unique within the import. Failures are reported by it.

rows[].externalCustomerIdstringRequired

rows[].namestring

rows[].phonestring

Bangladesh in any form, or +<country><number>. Never returned.

rows[].emailemail

rows[].localestring

Returns 200

invalidintegerRequired

totalintegerRequired

validintegerRequired

rowsobject[]Required

rows[].alreadyMemberbooleanRequired

rows[].codestring or nullRequired

rows[].fieldsstring[]Required

rows[].rowRefstringRequired

rows[].validbooleanRequired

Queue a batch of customers to be enrolled in a program

Scopecustomers:write

Requires customers:write and an Idempotency-Key. Up to 100 rows and 16 KiB of JSON per import (a larger migration is many imports; more than five waiting or running is 429 IMPORT_BACKLOG). Answers 202 with a jobId once the batch is recorded: queued means nothing has been enrolled yet. Rows with a bad field are accepted as failed rows that name their rowRef (INVALID_ROW); a bad envelope, a repeated rowRef or more than 100 rows is 422. Each row is enrolled exactly as POST /programs/{id}/memberships does it, by your own customer id: no consent is recorded, an existing opt-out is kept and a repeat is existing, never a second membership. Read the job and its rows to follow progress.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

branchIduuid

The branch the customers join at; omitted, the program's own or first open one.

rowsobject[]Required

rows[].rowRefstringRequired

Your own reference for this row; unique within the import. Failures are reported by it.

rows[].externalCustomerIdstringRequired

rows[].namestring

rows[].phonestring

Bangladesh in any form, or +<country><number>. Never returned.

rows[].emailemail

rows[].localestring

Returns 202

invalidintegerRequired

Rows already recorded as failed because they were not well formed.

jobIdstringRequired

programIdstringRequired

statusenumRequired

One of queued, running, completed.

totalintegerRequired

Errors

• 429IMPORT_BACKLOGthe business already has the most customer imports waiting or running it may have. Nothing was queued; retry when one finishes.

Read an import's progress

Scopecustomers:write

Requires customers:write. Counts come from the rows. status is completed only when no row is pending; queued and running mean work is still to do. An import of another application, business or environment is 404.

Path

jobIduuidRequired

Returns 200

completedAtstring or nullRequired

createdintegerRequired

createdAtstringRequired

existingintegerRequired

failedintegerRequired

jobIdstringRequired

pendingintegerRequired

programIdstringRequired

retryableintegerRequired

Failed rows a retry would try again.

startedAtstring or nullRequired

statusenumRequired

One of queued, running, completed.

totalintegerRequired

Read each row's outcome

Scopecustomers:write

Requires customers:write. Rows come in the order sent, limit 1 to 50 (default 25), optional status filter. A row is named by your rowRef; no name, phone or email is ever returned, and a failure carries a fixed code (INVALID_ROW, CUSTOMER_REFERENCE_CONFLICT, a plan refusal such as PLAN_READ_ONLY, EXPIRED, INTERNAL) and the names of refused fields.

Path

jobIduuidRequired

Query

limitinteger

1 to 50. Default 25.

offsetinteger

Default 0.

statusenum

One of pending, created, existing, failed.

Returns 200

hasMorebooleanRequired

itemsobject[]Required

items[].codestring or nullRequired

items[].customerIdstring or nullRequired

items[].externalCustomerIdstring or nullRequired

items[].fieldsstring[]Required

Names of refused fields, never values.

items[].membershipIdstring or nullRequired

items[].messagestring or nullRequired

items[].positionintegerRequired

items[].retryablebooleanRequired

items[].rowRefstringRequired

items[].statusenumRequired

One of pending, created, existing, failed.

limitintegerRequired

offsetintegerRequired

Try an import's retryable failed rows again

Scopecustomers:write

Requires customers:write and an Idempotency-Key. Only a completed import can be retried (409 IMPORT_NOT_FINISHED otherwise). Rows that failed for a reason that can pass later (a plan refusal, an unexpected error) and whose details Revisit still holds (seven days) go back to the queue; bad rows and conflicts do not (retryable: false). Rows already enrolled are never repeated.

Send an Idempotency-Key header. Safe to retry.

Path

jobIduuidRequired

Returns 200

jobIdstringRequired

requeuedintegerRequired

statusenumRequired

One of queued, running, completed.

Errors

• 409IMPORT_NOT_FINISHEDa retry was asked of an import that is still queued or running.

List this application's recent exports

Scopecustomers:export

Requires customers:export. The newest 20 exports of this application, most recent first.

Returns 200

itemsobject[]Required

items[].exportIdstringRequired

items[].statusenumRequired

One of ready, expired.

items[].rowCountintegerRequired

Rows in the file; 0 once it is gone.

items[].createdAtdate-timeRequired

items[].expiresAtdate-timeRequired

items[].downloadPathstring or nullRequired

Set only while the file can be downloaded.

items[].expiredReasonenum or nullRequired

One of time, customer_erased.

items[].programIdstring or nullRequired

items[].branchIdstring or nullRequired

Export customers to a CSV file

Scopecustomers:export

Requires customers:export and an Idempotency-Key. The scope is never part of the Read-only or Full access presets: an owner ticks it under "Choose permissions". The file holds the customers and memberships this key may already read (GET /customers), one row per membership, with the same masked phone (•••• 1234); a whole phone number and an email are never in it. Name cells that start with =, +, - or @ get a leading apostrophe so a spreadsheet never runs them. The file is built inside the request, so status is ready when this answers (a refusal answers an error, never a half file). At most 5,000 customers per file (422 EXPORT_TOO_LARGE: narrow by programId or branchId), 5 exports an hour per key (429), and 5 ready files per business (429 EXPORT_BACKLOG). A file can be downloaded for 24 hours and only by the application that made it. A repeat with the same key replays the same export (Idempotent-Replay).

Send an Idempotency-Key header. Safe to retry.

Body

programIduuid

branchIduuid

Returns 200

exportIdstringRequired

statusenumRequired

One of ready, expired.

rowCountintegerRequired

Rows in the file; 0 once it is gone.

createdAtdate-timeRequired

expiresAtdate-timeRequired

downloadPathstring or nullRequired

Set only while the file can be downloaded.

expiredReasonenum or nullRequired

One of time, customer_erased.

programIdstring or nullRequired

branchIdstring or nullRequired

Errors

• 422EXPORT_TOO_LARGEmore customers match than one export holds; narrow it by program or branch.
• 429EXPORT_BACKLOGthe business already holds the most ready exports it may; wait for one to expire.

Read an export's status

Scopecustomers:export

Requires customers:export. status is ready (with downloadPath) or expired. An export expires when its 24 hours pass (expiredReason: time) or when any customer in it is erased (customer_erased): the file is wiped at once. An export of another application, business or environment is 404.

Path

exportIduuidRequired

Returns 200

exportIdstringRequired

statusenumRequired

One of ready, expired.

rowCountintegerRequired

Rows in the file; 0 once it is gone.

createdAtdate-timeRequired

expiresAtdate-timeRequired

downloadPathstring or nullRequired

Set only while the file can be downloaded.

expiredReasonenum or nullRequired

One of time, customer_erased.

programIdstring or nullRequired

branchIdstring or nullRequired

Download an export file

Scopecustomers:export

Requires customers:export. Sends the CSV (text/csv, Content-Disposition: attachment, Cache-Control: no-store, X-Content-Type-Options: nosniff, and X-Export-Sha256 of the body). The first line is the header: customer_id, external_customer_id, member_code, name, masked_phone, locale, customer_created_at, membership_id, program_id, card_type, balance, lifetime_earned, marketing_opt_in, consent_source, consent_at, joined_at, joined_branch_id, last_activity_at. 410 EXPORT_EXPIRED once the file is gone. Each download is audited.

Path

exportIduuidRequired

Errors

• 410EXPORT_EXPIREDthe export file is gone (its day passed, or a customer in it was erased). Make a new export.