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

# Terms acceptance

> Create a terms link, send termsAcceptance on Create customer, and the terms error codes

Before Endl can create a customer for you, the customer must accept Endl's terms. You
prove that acceptance by sending `termsAcceptance` on
[Create customer](https://docs.endl.io/api-reference/onboarding/create-customer.md) (`POST /api/v0/customer`).

There are two ways to collect the acceptance:

| Option | How it works | What you send on Create customer |
| - | - | - |
| **A. Endl's hosted terms page** (recommended) | Endl hosts the page. You show it to the customer in an iframe or by redirecting them. Endl records the acceptance and gives you a signed agreement id. | `{ "signed_agreement_id": "<uuid>" }` |
| **B. Your own terms screen** | You show [Endl's platform terms](https://www.endl.io/legal/platform-terms/) in your own app and record the acceptance yourself. | `{ "acceptance_token": "<uuid>", "ipAddress": "…", "version": "v1", "userAgent": "…" }` |

> [card] [Hosted terms page guide](https://docs.endl.io/guides/terms-acceptance.md)
>
> Showing the hosted page in an iframe or by redirect, the `endl.terms.*` events,
> what the customer sees, security, a test checklist and an FAQ.

## Flow with the hosted page

**1. Your backend creates a terms link**

[`POST /api/v0/terms/links`](https://docs.endl.io/api-reference/onboarding/create-terms-link) returns
`{ url, expires_at }`.

**2. You show the url to the customer**

In an iframe or as a full page — see the
[hosted terms page guide](https://docs.endl.io/guides/terms-acceptance.md).

**3. The customer accepts**

Endl gives you the signed agreement id, by `postMessage` (iframe) or by redirect.

**4. Your backend creates the customer with it**

[`POST /api/v0/customer`](https://docs.endl.io/api-reference/onboarding/create-customer) with
`termsAcceptance` — see [below](#send-termsacceptance-on-create-customer).

* A link works only once and expires. `expires_at` in the response says when; links
  currently last 15 minutes.
* The signed agreement id is created only when the customer accepts. Endl sends it to
  you once, and no endpoint returns it again, so save it when it arrives.
* Each signed agreement id can be used for one customer only.

## Create a terms link

```bash theme={null}
curl -X POST https://api-sandbox.endl.io/api/v0/terms/links \
  -H "Api-Version: 2026-09.1" \
  -H "Api-Key: $ENDL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_uri": "https://partner.example/endl/done" }'
```

* `Api-Version` is required, as on every `/api/v0` request. If it's missing or the value
  isn't supported, the request fails with `400` and `field: "Api-Version"`.
* `redirect_uri` is only needed for redirect mode. Leave it out for an iframe-only link.
  Sent blank (`""` or only spaces), it is `400 ERRCUS_1712`.

See [Create terms link](https://docs.endl.io/api-reference/onboarding/create-terms-link.md) for the full
request, response and errors, and the
[hosted terms page guide](https://docs.endl.io/guides/terms-acceptance.md) for how to show the returned `url`.

## Send `termsAcceptance` on Create customer

`termsAcceptance` is required on `POST /api/v0/customer` for:

* individual customers, created with full data or imported with a `shareToken`
* business customers, created with full data or imported with a `shareToken`

It's checked before anything else. If it's missing or invalid, the request fails with
`400` and only the terms errors, and no customer is created.

**Send exactly one of the two proofs.**

> [tab] A. Signed agreement (hosted page)
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `termsAcceptance.signed_agreement_id` | string (UUID) | Yes | The signed agreement id from the hosted page (postMessage or redirect). It must belong to your partner account, be accepted, be for the current terms, and not already be used for another customer. |
>
> ```json theme={null}
> {
>   "userType": "INDIVIDUAL",
>   "email": "jane.doe@example.com",
>   "firstName": "Jane",
>   "lastName": "Doe",
>   "termsAcceptance": {
>     "signed_agreement_id": "3a828266-e924-4875-b01b-e1ff95735a5f"
>   }
> }
> ```

> [tab] B. Acceptance on your own screen
>
> Show the customer [Endl's platform terms](https://www.endl.io/legal/platform-terms/)
> on your own screen before you send `termsAcceptance`.
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `termsAcceptance.acceptance_token` | string (UUID) | Yes | A UUID you generate for this acceptance. Each token can be used only once. |
> | `termsAcceptance.ipAddress` | string | Yes | The customer's IP address when they accepted (IPv4 or IPv6). |
> | `termsAcceptance.version` | string | Yes | The terms version the customer accepted. It must be the current version: `v1`. |
> | `termsAcceptance.userAgent` | string | No | The customer's browser user agent. Max 512 characters. |
>
> ```json theme={null}
> {
>   "userType": "INDIVIDUAL",
>   "email": "jane.doe@example.com",
>   "firstName": "Jane",
>   "lastName": "Doe",
>   "termsAcceptance": {
>     "acceptance_token": "c1f0e6a2-7b4d-4e19-9a3c-5d8e2f1b6a70",
>     "ipAddress": "203.0.113.7",
>     "version": "v1",
>     "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15"
>   }
> }
> ```

The other customer fields are shortened in these examples. Send the full request as
described on the [Create customer](https://docs.endl.io/api-reference/onboarding/create-customer.md) page.

> [!WARNING]
>
> **Breaking change:** a Create customer request without `termsAcceptance` now fails
> with `400 ERRCUS_1700`.

## Errors

### 400 validation errors

| Code | Field | Message |
| - | - | - |
| `ERRCUS_1700` | `termsAcceptance` | `termsAcceptance is required` |
| `ERRCUS_1701` | `termsAcceptance` | `termsAcceptance must be an object` |
| `ERRCUS_1706` | `termsAcceptance.ipAddress` | `termsAcceptance.ipAddress is required` |
| `ERRCUS_1707` | `termsAcceptance.ipAddress` | `termsAcceptance.ipAddress is not a valid IPv4 or IPv6 address` |
| `ERRCUS_1708` | `termsAcceptance.version` | `termsAcceptance.version is required` |
| `ERRCUS_1709` | `termsAcceptance.version` | `termsAcceptance.version is not a valid version` |
| `ERRCUS_1710` | `termsAcceptance.version` | `termsAcceptance.version is not the current terms version` |
| `ERRCUS_1711` | `termsAcceptance.userAgent` | `termsAcceptance.userAgent is not a valid user agent` |
| `ERRCUS_1712` | `redirect_uri` | `redirect_uri is not an absolute https:// URL` (Create terms link) |
| `ERRCUS_1712` | `redirect_uri` | `redirect_uri must not be blank; leave it out for the iframe flow` — sent as `""` or only spaces (Create terms link) |
| `ERRCUS_1713` | `termsAcceptance` | `termsAcceptance needs acceptance_token or signed_agreement_id` |
| `ERRCUS_1714` | `termsAcceptance` | `termsAcceptance takes acceptance_token or signed_agreement_id, not both` |
| `ERRCUS_1715` | `termsAcceptance.acceptance_token` | `termsAcceptance.acceptance_token is not a UUID` |
| `ERRCUS_1716` | `termsAcceptance.signed_agreement_id` | `termsAcceptance.signed_agreement_id is not a UUID` |

### Signed agreement and acceptance token errors

| Code | HTTP | Field | Meaning | What to do |
| - | - | - | - | - |
| `ERRCUS_1611` | 409 | `termsAcceptance.signed_agreement_id` | The customer hasn't accepted the terms on this link yet | Have the customer accept on the hosted page first. |
| `ERRCUS_1612` | 409 | `termsAcceptance.signed_agreement_id` | The signed agreement is already used by another customer | Create a new link and have this customer accept. |
| `ERRCUS_1613` | 409 | `termsAcceptance.acceptance_token` | The acceptance token is already used | Generate a new `acceptance_token` for each acceptance. |
| `ERRCUS_1614` | 409 | `termsAcceptance.signed_agreement_id` | The signed agreement isn't for the current platform terms | Open a new terms link so the customer accepts the current terms. |
| `ERRCUS_1717` | 400 | `termsAcceptance.signed_agreement_id` | An unknown signed agreement, or one created by a different partner | Use a signed agreement id your own terms link returned. |

## Testing

1. Get a signed agreement id on sandbox by following the
   [hosted terms page testing steps](https://docs.endl.io/guides/terms-acceptance.md#testing).
2. Create the customer with that `signed_agreement_id` in `termsAcceptance`.
3. Send the same `signed_agreement_id` on a second Create customer request. You should
   get `409 ERRCUS_1612`.
4. Make sure `termsAcceptance` is sent on every Create customer request.


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