> ## 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.

# Hosted terms page

> Show Endl's terms to your customer in an iframe or by redirect, and get back the signed agreement id

Before Endl can create a customer for you, the customer must read and accept Endl's
terms. Endl hosts the page that does this. You show it to the customer and get back a
**signed agreement id**, which you pass to Endl when you create the customer.

This guide covers the hosted page from your side. The API calls — creating a terms
link, sending `termsAcceptance` on Create customer, and the error codes — are in the
API reference: [Terms acceptance](https://docs.endl.io/api-reference/onboarding/terms-acceptance.md) and
[Create terms link](https://docs.endl.io/api-reference/onboarding/create-terms-link.md).

You can show the page in one of two ways:

| Mode | When to use | How you receive the signed agreement id |
| - | - | - |
| **Iframe** (recommended) | You want the customer to stay inside your app or site | A `postMessage` event to your page |
| **Redirect** | You can't embed an iframe, for example in some mobile webviews or email links | Your `redirect_uri`, with `?signed_agreement_id=…` added |

## How it works

**1. Your backend asks Endl for a terms link**

[Create terms link](https://docs.endl.io/api-reference/onboarding/create-terms-link.md) returns the `url`
to show.

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

In an [iframe](#iframe-integration-recommended), or as a
[full page](#redirect-integration).

**3. The customer accepts**

They read the terms, scroll to the end, tick the box and click
**Accept and continue**.

**4. Endl records the acceptance and gives you the signed agreement id**

By `postMessage` (iframe) or by redirect.

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

Send it as `termsAcceptance.signed_agreement_id` on
[Create customer](https://docs.endl.io/api-reference/onboarding/terms-acceptance.md#send-termsacceptance-on-create-customer).

* The **link** is single-use and expires. The expiry time is returned when it is
  created.
* The **signed agreement id** is created only when the customer accepts. It is
  delivered **once**, and no endpoint gives it to you again, so capture it when it
  arrives.

## Getting a link

Your backend creates the link with
[Create terms link](https://docs.endl.io/api-reference/onboarding/create-terms-link.md)
(`POST /api/v0/terms/links`). Send a `redirect_uri` — an absolute `https://` URL on
your side — only for redirect mode. Leave it out for an iframe-only link.

Use the returned `url` **exactly as returned**. In particular:

* **`env`:** links for test environments carry `&env=qa` or `&env=sandbox`.
  Production links have no `env`. Don't add, remove or change it.
* **`redirect_uri`:** never put it in the page URL yourself. It is stored with the
  link when the link is created; a `redirect_uri` added to the page URL is ignored.

## Iframe integration (recommended)

### Add the listener, then the iframe

Register the listener **before** setting the iframe `src`, so you don't miss an
early event.

```html theme={null}
<iframe
  id="endl-terms"
  title="endl terms"
  style="width: 100%; height: 700px; border: 0;"
></iframe>

<script>
  const ENDL_ORIGIN = 'https://www.endl.io';
  const frame = document.getElementById('endl-terms');

  window.addEventListener('message', (event) => {
    // 1. Only accept messages from endl...
    if (event.origin !== ENDL_ORIGIN) return;
    // 2. ...coming from YOUR iframe.
    if (event.source !== frame.contentWindow) return;

    const data = event.data || {};

    switch (data.type) {
      case 'endl.terms.accepted':
        // The customer accepted. Send the id to YOUR backend, which creates
        // the customer with endl.
        fetch('/your-backend/endl/terms-accepted', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ signedAgreementId: data.signedAgreementId }),
        });
        frame.remove(); // or close your modal
        break;

      case 'endl.terms.expired':
        // The link is invalid, expired or already used. This is final.
        // Request a new link if the customer still needs to accept.
        break;

      case 'endl.terms.error':
        // A temporary problem on endl's side. The page offers the customer a
        // retry, so you don't need to do anything.
        break;
    }
  });

  // Set src last — the URL your backend received from endl.
  frame.src = 'https://www.endl.io/legal/terms?link=tos_…&env=sandbox';
</script>
```

### Events

All events are sent with `window.parent.postMessage(message, '*')`. Match on `type`,
and use the exact strings below.

| `type` | Payload | When | Final? |
| - | - | - | - |
| `endl.terms.accepted` | `{ type: 'endl.terms.accepted', signedAgreementId: '<uuid>' }` | Right after the customer accepts | Yes |
| `endl.terms.expired` | `{ type: 'endl.terms.expired' }` | The link is unknown, expired or already accepted, or it expires while the page is open | Yes |
| `endl.terms.error` | `{ type: 'endl.terms.error' }` | Endl is temporarily unavailable, on load or on submit | No — the customer can retry |

```json Example accepted payload theme={null}
{ "type": "endl.terms.accepted", "signedAgreementId": "3a828266-e924-4875-b01b-e1ff95735a5f" }
```

* **After acceptance the frame stays put.** It shows "Terms accepted — You can close
  this window" and does not navigate. Close or hide it yourself.
* **Inside an iframe, Endl always uses `postMessage`**, even if the link has a
  `redirect_uri`. The iframe never redirects.
* **`endl.terms.expired` doesn't say why.** It doesn't distinguish expired from
  already-accepted.
* **`endl.terms.error` can fire more than once** if the customer retries.
* **The page only sends messages.** It ignores anything you post to it.

### Sizing and frame settings

* **Height:** about 600–800px. The terms scroll inside the frame, and the checkbox and
  button stay pinned at the bottom. Width works down to 320px, so phone screens are
  supported.
* **`sandbox` attribute:** not needed. If you use one, it must include at least
  `allow-scripts allow-same-origin allow-popups`. Links in the terms open in a new tab.
* **Cookies:** no cookies or `localStorage` are used, so third-party-cookie blocking
  has no effect.
* **Content-Security-Policy:** if your site sends one, allow Endl in `frame-src`:

  ```text theme={null}
  frame-src https://www.endl.io;
  ```

### React example

```jsx theme={null}
import { useEffect, useRef } from 'react';

export function EndlTerms({ url, onAccepted, onExpired }) {
  const frameRef = useRef(null);

  useEffect(() => {
    function onMessage(event) {
      if (event.origin !== 'https://www.endl.io') return;
      if (event.source !== frameRef.current?.contentWindow) return;
      if (event.data?.type === 'endl.terms.accepted') onAccepted(event.data.signedAgreementId);
      if (event.data?.type === 'endl.terms.expired') onExpired();
    }
    window.addEventListener('message', onMessage);
    return () => window.removeEventListener('message', onMessage);
  }, [onAccepted, onExpired]);

  return (
    <iframe ref={frameRef} src={url} title="endl terms"
            style={{ width: '100%', height: 700, border: 0 }} />
  );
}
```

## Redirect integration

Use this mode when you open the page as a normal tab or window instead of an iframe.

### Setup

[Create the link](https://docs.endl.io/api-reference/onboarding/create-terms-link.md) with a `redirect_uri`,
for example `https://partner.example/endl/done`. Then send the customer to the
returned `url`.

### What you receive

After the customer accepts, Endl sends the browser to your `redirect_uri` with the
signed agreement id added:

```text theme={null}
https://partner.example/endl/done?signed_agreement_id=3a828266-e924-4875-b01b-e1ff95735a5f
```

* Any query string already on your `redirect_uri` is kept, for example
  `…/done?ref=42&signed_agreement_id=…`.
* Endl uses `location.replace`, so the customer's Back button doesn't return to the
  spent terms page.

On your side, read the parameter and send it to your backend:

```js theme={null}
const signedAgreementId = new URLSearchParams(location.search).get('signed_agreement_id');
```

Server-side (Node/Express example):

```js theme={null}
app.get('/endl/done', async (req, res) => {
  const signedAgreementId = req.query.signed_agreement_id;
  if (!signedAgreementId) return res.status(400).send('Missing signed_agreement_id');
  await createEndlCustomer({ signedAgreementId });
  res.redirect('/onboarding/next-step');
});
```

### Links without a `redirect_uri`

A link created without a `redirect_uri` is **iframe-only**. If it is opened as a
normal page, the customer sees:

> **Please configure redirect URI to use this iframe-only link.**

The terms aren't shown, so the customer can't accept. To fix it, request a new link
that includes a `redirect_uri`, or show this link in an iframe.

## Which mode the page uses

The page detects for itself whether it is inside an iframe.

| Link has `redirect_uri`? | Shown in an iframe | Opened as a normal page |
| - | - | - |
| Yes | `postMessage` → `endl.terms.accepted` | Redirect to `redirect_uri?signed_agreement_id=…` |
| No | `postMessage` → `endl.terms.accepted` | "Please configure redirect URI…" screen |

## What the customer sees

| Screen | When |
| - | - |
| Terms text, a checkbox and **Accept and continue** | Valid link |
| Checkbox disabled — "Scroll to the end of the document to continue." | Until the customer scrolls to the bottom |
| Button disabled | Until the box is ticked, and while submitting |
| "We couldn't record your acceptance. Please try again." | Temporary Endl error on submit; the acceptance did **not** happen |
| "Terms accepted — You can close this window." | Accepted inside an iframe |
| "This link is no longer valid" | Unknown, expired or already-used link (no retry) |
| "Terms are temporarily unavailable" + **Try again** | Temporary Endl error on load |
| "Please configure redirect URI to use this iframe-only link." | Iframe-only link opened as a normal page |

## Security

* **Check `event.origin`.** Only accept messages where
  `event.origin === 'https://www.endl.io'` and `event.source` is your iframe. Any site
  can post messages to your page.
* **Treat the signed agreement id as sensitive.** It is proof that this customer
  accepted, so send it to your backend over HTTPS. Don't log it to analytics or error
  trackers, and don't show it to the customer.
* **Your `redirect_uri` must be `https://`.** Endl validates it when the link is
  created.
* **Use the link URL as Endl returns it.** Don't edit its query string.
* **The link id is not the signed agreement id.** Never send the `tos_…` link id where
  the signed agreement id is expected.

## Testing

1. Create a **test link** on sandbox (it carries `&env=qa` or `&env=sandbox`). Test
   links are free and unlimited.
2. Embed it with the [iframe code](#iframe-integration-recommended), or open it as a
   normal page for [redirect mode](#redirect-integration).
3. Scroll to the end, tick the box and accept. Check that:
   * **iframe:** your listener receives `endl.terms.accepted` with a
     `signedAgreementId`
   * **redirect:** your `redirect_uri` is hit with `?signed_agreement_id=…`
4. Open the same link again and check that you get `endl.terms.expired` (links are
   single-use).

To test the API side — creating the customer with the signed agreement id, and the
errors you get when you reuse it — see
[Terms acceptance → Testing](https://docs.endl.io/api-reference/onboarding/terms-acceptance.md#testing).

### Integration checklist

* [ ] Listener registered before the iframe `src` is set
* [ ] `event.origin === 'https://www.endl.io'` and `event.source` checked
* [ ] `endl.terms.accepted` → `signedAgreementId` sent to your backend; frame closed
* [ ] `endl.terms.expired` handled (request a new link)
* [ ] Redirect mode: `signed_agreement_id` read from the query and sent to your backend
* [ ] Link URL used exactly as returned (including `env`)
* [ ] Works at phone width
* [ ] Your CSP allows `frame-src https://www.endl.io` (if you use a CSP)

## FAQ

> [accordion] The iframe shows a broken-page icon.
>
> Either your site's CSP blocks Endl (add `frame-src https://www.endl.io`), or the
> link URL isn't on `https://www.endl.io`.

> [accordion] I got endl.terms.expired straight away.
>
> The link was already used, has expired, or the URL was changed. Request a new link.

> [accordion] Can I get the signed agreement id again later?
>
> No. It is delivered once. If you missed it, request a new link and have the
> customer accept again.

> [accordion] Can I style the page?
>
> No. The page shows only the terms, the checkbox and the button, so that it fits
> inside any partner's UI.

> [accordion] Does the page use cookies or tracking?
>
> No. It has no cookies, no `localStorage` and no analytics.


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