Customers

Create + manage end-user records on the Remittances API. The customer represents one of your end-users (e.g. a Pouch app user) for whom you’re moving money.

The customer object

{
  "object": "customer",
  "id": "ckcust_xxxxxxxxxxxx",
  "customer_reference": "pouch-user-12345",
  "interac_email": "user@pouch.app",
  "status": "verified",
  "env": "live",
  "created_at": "2026-01-15T10:00:00Z"
}

Status values

Status	Description
`pending`	Customer created, awaiting KYC verification
`verified`	KYC approved by our regulated verification partner; customer can transact
`rejected`	KYC rejected — see admin tooling for rejection reason
`closed`	Customer closed (rare — initiated by you or Technest)

The upstream rail’s internal customer_id is NOT exposed in the public API — Swappr translates it server-side on every payout/VIBAN call. You always reference customers by Swappr’s id (cuid) or customer_reference (your opaque ID).

Create a customer

POST /v1/customers

Creates a customer in our DB + provisions one upstream at our regulated KYC partner. Subsequent KYC docs + verification happen via separate endpoints.

Request

{
  "type": "individual",
  "first_name": "Adaeze",
  "last_name": "Okonkwo",
  "email": "adaeze@example.com",
  "country": "CA",
  "id_type": "passport",
  "id_number": "AB1234567",
  "phone": "+14165550100",
  "dob": "1992-10-15",
  "street": "100 King Street",
  "city": "Toronto",
  "state": "ON",
  "zip_code": "M5V 0E0",
  "tin": "123456789",
  "customer_reference": "pouch-user-12345",
  "interac_email": "adaeze@gmail.com"
}

Required fields

Field	Notes
`type`	`individual` \| `business`
`email`	Customer’s email
`country`	ISO 3166-1 alpha-2 (NG, CA, GB, US)
`id_type`	See country allowlist
`id_number`	National ID, passport, drivers’ license number, or business reg #
`tin`	Tax ID — country-specific format
`customer_reference`	Your unique ID for this customer. One per merchant.
`zip_code`	Postal code per country format

For type=individual: first_name, last_name, dob. For type=business: business_name.

Optional fields

phone, street, city, state, interac_email (CAD-only), id_expiry_date, id_issue_date.

Country-specific TIN format

Country	Format
NG	TIN: 10 digits OR variant with regulator prefix
CA	SIN: 9 digits
GB	UTR: 10 digits
US	SSN: 9 digits OR EIN for businesses

Example

curl https://api.swappr.me/v1/customers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "first_name": "Adaeze",
    "last_name": "Okonkwo",
    "email": "adaeze@example.com",
    "country": "CA",
    "id_type": "passport",
    "id_number": "AB1234567",
    "phone": "+14165550100",
    "dob": "1992-10-15",
    "street": "100 King Street",
    "city": "Toronto",
    "state": "ON",
    "zip_code": "M5V 0E0",
    "tin": "123456789",
    "customer_reference": "pouch-user-12345",
    "interac_email": "adaeze@gmail.com"
  }'

const res = await fetch('https://api.swappr.me/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'individual',
    first_name: 'Adaeze',
    last_name: 'Okonkwo',
    email: 'adaeze@example.com',
    country: 'CA',
    id_type: 'passport',
    id_number: 'AB1234567',
    dob: '1992-10-15',
    zip_code: 'M5V 0E0',
    tin: '123456789',
    customer_reference: 'pouch-user-12345',
    interac_email: 'adaeze@gmail.com',
  }),
});
const customer = await res.json();

res = requests.post(
    'https://api.swappr.me/v1/customers',
    headers={
        'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}",
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json',
    },
    json={
        'type': 'individual',
        'first_name': 'Adaeze',
        'last_name': 'Okonkwo',
        'email': 'adaeze@example.com',
        'country': 'CA',
        'id_type': 'passport',
        'id_number': 'AB1234567',
        'dob': '1992-10-15',
        'zip_code': 'M5V 0E0',
        'tin': '123456789',
        'customer_reference': 'pouch-user-12345',
        'interac_email': 'adaeze@gmail.com',
    },
)
customer = res.json()

Response

201 Created with the customer object on first create, OR 200 OK if the customer_reference already existed (idempotent replay).

Errors

Code	HTTP	Cause
`country_not_supported`	400	Country not in NG/CA/GB/US
`invalid_field`	400	id_type / tin / zip_code format mismatch
`customer_already_exists`	409	customer_reference + email already used
`interac_email_taken`	409	Same `interac_email` already on another customer
`provider_error`	502	Upstream rail unreachable; retry with same idempotency key

List customers

GET /v1/customers

Cursor-paginated.

Param	Notes
`limit`	1-100, default 50
`starting_after`	Cursor
`status`	Filter — `pending` \| `verified` \| `rejected` \| `closed`
`q`	Search by `customer_reference`, `interac_email`, or display name (case-insensitive)

Retrieve a customer

GET /v1/customers/{id}

Accepts cuid OR customer_reference.

Update a customer

PATCH /v1/customers/{id}

Narrow scope — only non-identity fields can be updated:

email, phone, street, city, state, zip_code, dob, id_expiry_date

Identity fields (name, country, id_type, id_number, tin) are immutable once the customer has been provisioned upstream. If you need to change them, the customer must be rejected + you create a fresh one with a new customer_reference.

Request

{
  "phone": "+14165550199",
  "street": "200 Bay Street",
  "city": "Toronto"
}

Response

200 OK with updated customer.

Getting started