Skip to content
Athena User Guide
Esc
↑↓navigate↵open⌘Jpreview
On this page

Form embed API

The address behind a JSON embed, and submitting a response from your own interface.

A JSON embed lets your own interface collect a form’s answers and send them to Athena. Create the embed from the Embeds page of the form (see Embed a form on your site), then open it there for a worked example carrying your form’s actual question ids.

There is one address, and it takes a response:

POST /api/forms/embed/KEY/responses

KEY is your embed’s key, and the address sits on the same host as your Athena dashboard. It carries no API key: the key in the path identifies the form, and the embed’s list of allowed sites decides who may post to it.

The questions themselves aren’t served over HTTP. Your interface is built against the form as it stands when you copy the snippet, and the Keeping in step with the form section below covers what happens when an organizer changes it.

Who may call it

Every request must come from a browser page on one of the embed’s listed sites: the browser’s own Origin is what’s checked, and it must match one of them exactly. A request with no origin at all is refused, so responses can only be sent from a page, never from your backend on a respondent’s behalf.

A call from a site that isn’t listed, or to an embed that’s switched off or deleted, is refused too.

Sending a response

{
  "specVersion": 4,
  "answers": {
    "q-a1b2c3d4": "Ada Lovelace",
    "q-e5f6g7h8": ["ctf", "training"]
  },
  "metadata": { "source": "pricing-page" },
  "idempotencyKey": "8f14e45f"
}

Only answers is required.

  • answers is keyed by question id, with the value shape each question type expects; see the table below.
  • metadata carries the keys this embed declares as passed-in values; anything else is dropped. Values the embed records itself always win over a passed-in key of the same name.
  • idempotencyKey is any string unique to one attempt. Retrying with the same key won’t record a second response, which is worth having if respondents are on flaky connections.
  • specVersion is the number shown in the snippet. Optional, and recommended: it turns a form change into one clear error instead of a scatter of field errors.

Answer shapes

Question type Answer to send Notes
short_text, long_text string Capped at the question’s own limit when set, and at 5,000 characters regardless
email string Must look like an email address
url string Must be an http or https URL
number number The question may set a minimum and a maximum
single_select string One of the question’s option ids
multi_select array of strings Option ids, no duplicates
checkbox boolean A required checkbox must be true
date string YYYY-MM-DD

For choice questions, send the option id, which the snippet shows, not the label the respondent reads.

A question the respondent left blank can be omitted, unless it’s required.

Replies

Status Meaning
201 Recorded
400 The body isn’t JSON, or has no answers object
403 The calling site isn’t allowed, or no origin was sent
404 No such embed, it’s switched off, or the form is still a draft
409 The form stopped accepting responses, the rate limit was hit, the response was too large, or specVersion is stale
422 One or more answers failed validation

A 422 names the questions to fix, keyed by question id:

{
  "error": "Some answers need fixing.",
  "errors": { "q-a1b2c3d4": "This question is required." }
}

Show these against the matching fields; the strings are written for respondents to read.

A 409 carries a plain error string for the respondent. When it’s a stale specVersion, the current version comes with it:

{
  "error": "This form has changed since your integration was built. Fetch the form again and resubmit.",
  "specVersion": 5
}

Captcha

A JSON embed has no captcha. Athena’s captcha runs on an Athena page, which a JSON embed doesn’t have, so the Require captcha switch is off and unavailable when you pick this type.

Your interface is the only thing standing between the form and automated submissions, so add your own defences: a captcha of your own, a rate limit, or authentication if the page already sits behind a sign-in. Submissions are also rate limited per visitor on Athena’s side, but that is a backstop, not a substitute.

The Visual embed keeps its captcha, so if it’s the abuse surface you’re worried about rather than the styling, that type is the safer choice.

Keeping in step with the form

Your interface is written against the questions as they stood when you copied the snippet. An organizer editing the form, whether by adding a required question, changing a question’s type, or removing one, changes what a valid response looks like straight away; there’s no separate publish step for question changes.

Send specVersion with every response and you’ll get a single 409 naming the mismatch, rather than a 422 full of errors about questions your interface never knew about. Recovering means copying a fresh snippet from the form’s Embeds page and updating your interface to match. The questions aren’t served over HTTP, so this is a deliberate step rather than something your code can do on its own.

On the organizer’s side, the form editor warns before saving a question change while JSON embeds are live, and says how many.

Size limits

A response carrying more than 120 answers, or an answers object over 200,000 characters, is refused with 409 and “This response is too large.” Those ceilings sit well above any form built in the editor, which caps a form at 60 questions and each text answer at 5,000 characters.

Was this page helpful?