## Create and manage customers

## Resources at a glance

| Field | Purpose |
|  --- | --- |
| **id** | Immutable Adfin identifier, returned on creation of the customer. |
| **name** | Legal name of the customer (business or individual). |
| **people[]** | Optional contacts (each can have a name, email, and phone). Can be allocated as primary contact, and included in communications. |
| **addresses[]** | A list of addresses for the customer. Currently, only one address is supported. |
| **externalData[]** | Key-value pairs to connect with accounting platforms. |


br
## Create a customer

Use customers to store information, either for an individual or a business.

Adfin users will look at Customers, to understand their credit control status, their direct debit status and activity.


```js index.js
{
  "name": "John Doe Ltd",
  "people": [
    { "name": "John Doe", "email": "john@doe-ltd.co.uk" }
  ],
  "addresses": [
    { "line1": "2 Catherine Pl", "city": "London", "postCode": "SW1E 6HF" }
  ],
}
```

br
## Direct debits for customers

Endpoint: `GET /customers/[id]/directdebitmandates`

1. Call GET /customers/[id]/directdebitmandates with a JSON body containing a redirectUrl to bring the user back to your app (it is also returned in the create customer response).
2. We return a URL — send the customer there to sign the mandate.
3. Listen for the dd-mandate. Updated webhook to know when status moves to ACTIVE.


Direct debit patterns
Check out [Direct Debit integration patterns guide](/products/direct-integration/guides/design-patterns/2-direct-debit).

Where you can learn how to enforce signature, set redirects and use pop-ups.

 Cancel Mandate 

If you ever need to void a mandate (e.g., customer changed bank), call

`PUT /customers/directdebitmandates/[id]:cancel`.

br
## List & search customers

Endpoint: GET /customers

Supports rich server-side filtering so you rarely need client-side joins.

br
| Query Parameter | Example use |
|  --- | --- |
| searchText | Fuzzy search on name, email |
| onlyCustomersWithActivity=true | Show customers who have invoices or mandates |
| ddMandateStatuses=ACTIVE | Pre-filter by mandate status |
| financialStatus=OVERDUE | Surface at-risk customers as part of credit control |
| Pagination | Page & Size |


br
## Best practices

1. Create once, reuse forever – keep the Adfin customer ID in your DB.
2. Attach mandate ASAP – trigger mandate creation right after sign-up so future invoices auto-collect.
3. Sync contacts – push updated emails or addresses with PUT /customers whenever they change.
4. Stay event-driven – subscribe to customer, updated, and dd-mandate. Updated to mirror state instantly.