> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swipelux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Create the individual or business Swipelux customer that owns capabilities, wallets, bank accounts, and transfers, and attach the right onboarding profile.

Create the customer before you build a pay-in, payout, or issued bank account. Capabilities, accounts, and transfers are scoped to that customer. Use `externalId` as the stable mapping to the corresponding record in your system.

```bash Environment variables theme={null}
export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'
```

## Individual customers

An individual requires only `type`. Include profile fields you already know, and add more only when the current capability or task needs them.

Create the customer with [`POST /v3/customers`](https://docs.swipelux.com/api-reference/customers/post-v3-customers):

```bash Create individual customer theme={null}
curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-user-123" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "individual",
  "externalId": "user_123",
  "individual": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON
```

Store the returned `data.id` as `CUSTOMER_ID`. See [Individual onboarding](https://docs.swipelux.com/knowledge-base/individual-onboarding/overview.md) for policy context.

## Business customers

A business requires `business.legalName`. Create the business with the same operation:

```bash Create business customer theme={null}
curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-company-456" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "business",
  "externalId": "company_456",
  "business": {
    "legalName": "Acme Payments SAS"
  }
}
JSON
```

Store the returned `data.id` as `CUSTOMER_ID`. See [Business onboarding](https://docs.swipelux.com/knowledge-base/business-onboarding/overview.md) for policy and document context.

## Add business related parties

Add directors, owners, and other business participants when they are known or requested. This example creates a director with [`POST /v3/customers/{customerId}/related-parties`](https://docs.swipelux.com/api-reference/customers/post-v3-customers-by-customer-id-related-parties):

```bash Add related party theme={null}
curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/related-parties" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: related-party-director-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "partyType": "person",
  "roles": ["director"],
  "title": "Chief executive officer",
  "person": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON
```

Store the returned `data.id` as `RELATED_PARTY_ID`.

If you need to export a customer, use [`POST /v3/customers/{customerId}/export`](https://docs.swipelux.com/api-reference/customers/post-v3-customers-by-customer-id-export) and follow its request schema. The `json_basic_data` format returns the current public v3 customer resource as a JSON attachment; each call recomputes current data and excludes documents and document metadata.

For a portability-token format, send the receiving KYC project's client ID as `forClientId`, not the Swipelux `customerId`. Use the returned `data.token` before `data.expiresAt`. Reusing the same `Idempotency-Key` and body replays that token result; use a new key to issue another token.

## Read readiness from capabilities

A customer does not have a verification or readiness status in the API. Read the customer with [`GET /v3/customers/{customerId}`](https://docs.swipelux.com/api-reference/customers/get-v3-customers-by-customer-id) for current profile data, then use capabilities and their `openTaskIds` to decide what the customer can do next.

```bash Get customer theme={null}
curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"
```

### Find customers with outstanding documents

To find which customers on a page still owe mandatory documents, pass `include=documentRequirements` to [`GET /v3/customers`](https://docs.swipelux.com/api-reference/customers/get-v3-customers). You can combine it with capability summaries as `include=capabilities,documentRequirements`. API keys need `accounts:read` for the `documentRequirements` expansion.

Each customer summary then includes a `documentRequirements` object:

```json Document requirement summary theme={null}
{
  "documentRequirements": {
    "required": true,
    "count": 2
  }
}
```

* `count` is the number of mandatory document requirements in `action_required` on tasks that are also in `action_required`. It covers every task scope, including account-wide tasks, and does not depend on capability readiness.
* `required` is `true` when `count` is greater than `0`.
* A set of alternatives counts once, and only when every alternative requires a document.

The summary is conservative. It excludes optional documents, conditionally required documents, and alternatives that mix document and non-document routes. It also excludes requirements the customer can complete through hosted verification. As a result, `required: false` does not prove that no document task applies. Use it to prioritize customers, then read their tasks for the authoritative list of what to collect. Without the expansion, the response omits `documentRequirements`.

## Read customer transfer volume

To show how much money a customer has moved, call `GET /v3/customers/{customerId}/transfer-totals`. API keys need `customers:read`. An unknown customer returns `404 customer_not_found`.

```json Transfer totals theme={null}
{
  "data": {
    "customerId": "cus_...",
    "received": { "amount": "1000.00", "currency": "USD" },
    "sent": { "amount": "25.00", "currency": "USD" }
  }
}
```

* Only completed transfers count. Pending and failed transfers are excluded.
* `received` sums pay-ins and inbound wallet transfers from other customers. `sent` sums payouts and outbound wallet transfers.
* USD, USDC, and USDT count 1:1 as USD. Amounts in other currencies are excluded.
* Transfers between the customer's own wallets are excluded.
* Each `amount` is a decimal string with two places, and `"0.00"` when no transfers qualify.

The totals are movement volume, not a current balance.

Next, continue to [Capabilities and tasks](https://docs.swipelux.com/integration/onboarding/capabilities-and-requirements.md) to discover and activate the product outcome you need.


## Related topics

- [Get customer](https://docs.swipelux.com/api-reference/customers/get-v3-customers-by-customer-id.md)
- [Archive customer](https://docs.swipelux.com/api-reference/customers/delete-v3-customers-by-customer-id.md)
- [Create customer](https://docs.swipelux.com/api-reference/customers/post-v3-customers.md)
- [List customers](https://docs.swipelux.com/api-reference/customers/get-v3-customers.md)
- [Update customer](https://docs.swipelux.com/api-reference/customers/patch-v3-customers-by-customer-id.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.