Skip to Content
Elido is in closed beta — APIs are stable but rate-limits and quotas may change before GA. Request access →
GuidesCTA overlays

CTA overlays

A CTA overlay opens the link’s destination in a full-page frame and draws your message on top of it. It is available on Pro, Business and Enterprise. The edge serves it only when the destination allows framing: Elido checks the destination’s X-Frame-Options and CSP frame-ancestors headers in the background when you attach an overlay and again every day. Until the check passes, and for sites that forbid framing, visitors get a normal redirect.

Positions

positionWhat visitors see
bottom_barA bar along the bottom of the page (up to 640 px wide, centred)
top_barThe same bar along the top
bottom_rightA floating card in the bottom-right corner (360 px)
bottom_leftA floating card in the bottom-left corner
modal_centerA centred dialog over a dimmed backdrop; Esc or a click on the backdrop closes it

On screens narrower than 560 px the corner cards become a bottom sheet and bars stretch to the screen width. Every position has a close button.

Types and the fields they use

The overlay object has one flat set of fields. Each cta_type uses them as follows; the API answers 422 when the fields do not fit the type.

cta_typeheadlinebody_textbutton_textbutton_urlother
text_buttonrequiredoptionalrequiredrequiredimage_url
email_capturerequiredoptionalsubmit label (optional)privacy policy (optional)image_url
discount_coderequiredoptionalthe code, max 40shop link (optional)image_url
social_followrequired1-8 profile URLs, one per line--
surveythe question2-6 answers, one per line, max 80thank-you text (optional)-
custom_htmloptional---custom_html (required, max 10 000)

Limits: headline 200 characters, body text 1000, button text 80, URLs 2048 (absolute http/https only). Colours are #rgb or #rrggbb.

  • Discount code shows the code with a Copy button; copying counts as a click.
  • Social follow shows one button per profile, labelled with the network name (Instagram, X, LinkedIn, YouTube, TikTok and about 25 others; any other site shows its host name).
  • Survey shows the answers as buttons. One click records the answer.
  • Email capture shows an email field, a consent line (“By subscribing I agree to receive emails from the owner of this link. You can unsubscribe at any time”, shown next to an unticked checkbox the visitor must tick) and, if you set button_url, a link to your privacy policy.
  • Custom HTML is shown in a sandboxed frame inside the card: no scripts, no forms, no requests except https images; links open in a new tab. The frame is sized to its content, estimated from the markup because the frame has no scripts (at most 160 px in a bar, 260 px in a corner card, 360 px in the modal); longer content scrolls inside it.

Look and language

The card follows the visitor’s light or dark system theme. button_bg and button_text_color colour the button (and the Copy button); bg_color and text_color are stored but the card does not use them. The fixed labels (Close, Copy, Subscribe, the consent line, “Powered by Elido”) appear in the visitor’s browser language, in the 13 product languages. Your own text is shown as written.

Create an overlay

curl -X POST https://api.elido.app/v1/workspaces/1/cta \ -H "Authorization: Bearer $ELIDO_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Newsletter modal", "cta_type": "email_capture", "position": "modal_center", "headline": "Get the monthly digest", "body_text": "One email a month, no spam.", "button_text": "Count me in", "button_url": "https://example.com/privacy" }'

Then attach it to a link with cta_overlay_id on POST /v1/links or PATCH /v1/links/{id}, or pick it in the link editor.

PATCH /v1/workspaces/{id}/cta/{cta_id} changes only the fields you send; send "" to clear a text field.

Collected answers

Email and survey answers are stored per overlay. Read them in the dashboard under CTA overlays → Answers, or through the API:

curl https://api.elido.app/v1/workspaces/1/cta/42/submissions \ -H "Authorization: Bearer $ELIDO_TOKEN" # {"items":[{"id":7,"kind":"email","email":"[email protected]","link_id":12,...}], # "total":1,"answers":[]}

?format=csv returns up to 1000 rows as CSV. DELETE /v1/workspaces/{id}/cta/{cta_id}/submissions/{submission_id} removes one answer, for example when a visitor asks you to erase their email. Reading and deleting answers needs the cta_submissions.view permission, which admins and owners have by default.

Details of the visitor side:

  • The overlay page posts to POST https://api.elido.app/v1/public/cta/{cta_id}/submit.
  • One visitor can send 5 answers to an overlay at once, then one every 12 seconds; there is also a cap per overlay.
  • A repeat email for the same overlay is stored once.
  • No IP address or user agent is stored with an answer.
  • Elido does not send emails to these addresses. You are the controller of the list; export it to your email tool.

Tracking

The overlay records an impression when it is shown and a click when the visitor uses the button, copies the code, opens a social profile or sends an answer. GET /v1/workspaces/{id}/cta/{cta_id}/stats returns the totals.

What overlays do not do

  • Only the link’s main destination is framed. A/B variants and targeting rules get a normal redirect.
  • Encrypted links cannot use an overlay.
  • Bulk link creation does not accept cta_overlay_id.
  • There is no delay, exit-intent trigger or A/B test of overlay copy, and “Powered by Elido” cannot be removed.
  • Because of caching, a change to an overlay can take a few minutes to reach visitors.