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.
answersis keyed by question id, with the value shape each question type expects; see the table below.metadatacarries 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.idempotencyKeyis 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.specVersionis 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.