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.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.
Getting a link
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=qaor&env=sandbox. Production links have noenv. 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; aredirect_uriadded to the page URL is ignored.
Iframe integration (recommended)
Add the listener, then the iframe
Register the listener before setting the iframesrc, so you don’t miss an
early event.
Events
All events are sent withwindow.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 aredirect_uri. The iframe never redirects. endl.terms.expireddoesn’t say why. It doesn’t distinguish expired from already-accepted.endl.terms.errorcan 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.
-
sandboxattribute: not needed. If you use one, it must include at leastallow-scripts allow-same-origin allow-popups. Links in the terms open in a new tab. -
Cookies: no cookies or
localStorageare 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 aredirect_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 yourredirect_uri with the
signed agreement id added:
- Any query string already on your
redirect_uriis 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.
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.What the customer sees
Security
- Check
event.origin. Only accept messages whereevent.origin === 'https://www.endl.io'andevent.sourceis 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_urimust behttps://. 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
- Create a test link on sandbox (it carries
&env=qaor&env=sandbox). Test links are free and unlimited. - Embed it with the iframe code, or open it as a normal page for redirect mode.
- Scroll to the end, tick the box and accept. Check that:
- iframe: your listener receives
endl.terms.acceptedwith asignedAgreementId - redirect: your
redirect_uriis hit with?signed_agreement_id=…
- iframe: your listener receives
- Open the same link again and check that you get
endl.terms.expired(links are single-use).
Integration checklist
- Listener registered before the iframe
srcis set -
event.origin === 'https://www.endl.io'andevent.sourcechecked -
endl.terms.accepted→signedAgreementIdsent to your backend; frame closed -
endl.terms.expiredhandled (request a new link) - Redirect mode:
signed_agreement_idread 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
The iframe shows a broken-page icon.
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.I got endl.terms.expired straight away.
I got endl.terms.expired straight away.
The link was already used, has expired, or the URL was changed. Request a new link.
Can I get the signed agreement id again later?
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.
Can I style the page?
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.