Skip to main content
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 and Create terms link. You can show the page in one of two ways:

How it works

1

Your backend asks Endl for a terms link

Create terms link returns the url to show.
2

You show the url to the customer

In an iframe, or as a full page.
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.
  • 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.
Your backend creates the link with Create terms link (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.

Add the listener, then the iframe

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

Events

All events are sent with window.parent.postMessage(message, '*'). Match on type, and use the exact strings below.
Example accepted payload
  • 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:

React example

Redirect integration

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

Setup

Create the link 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:
  • 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:
Server-side (Node/Express example):
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.

What the customer sees

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, or open it as a normal page for redirect mode.
  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.

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

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.
The link was already used, has expired, or the URL was changed. Request a new link.
No. It is delivered once. If you missed it, request a new link and have the customer accept again.
No. The page shows only the terms, the checkbox and the button, so that it fits inside any partner’s UI.
No. It has no cookies, no localStorage and no analytics.