API 参考

Forms

Content Delivery API: GET /forms/{id}, GET /forms/{id}/challenge, POST /forms/{id}/upload-request, …

本页只有英文版。API 参考、Webhook 事件和更新日志保持英文，与代码中的字段名称、错误码一致。

Base URL https://{site}/api/v1Errors Pagination

GET/forms/{id}

betaNo auth

idstring · pathrequired
localestring · query
Locale for the form name, description, question labels, hints, choice labels, submit button and success message. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. Field and choice ids are locale-independent, so submissions are unaffected.

curl -X GET "https://{site}/api/v1/forms/{id}"

GET/forms/{id}/challenge

betaNo auth

provider"kanorio" | "turnstile" | "recaptcha" | "hcaptcha"required
entry"forms" | "customer_login"required
altchaobject
Built-in proof-of-work challenge (provider kanorio only).
altcha.algorithmstringrequired
altcha.challengestringrequired
altcha.maxnumberinteger
altcha.saltstringrequired
altcha.signaturestringrequired
siteKeystring
Widget site key (third-party providers).
actionstring
Pass this as the widget action; the server checks it.
cDatastring | null
Turnstile cData to pass to the widget; null for other providers.
recaptchaVersion"v2" | "v3" | null
visibleboolean
When true, show the check to the visitor instead of running it silently (the site is seeing unusual sign-in volume).
uploadTokenstring
Forms with a third-party provider only: send this as _tk (with _ctx set to the form id) when requesting file upload tickets. The widget token is single-use, so it is checked on submit instead.

curl -X GET "https://{site}/api/v1/forms/{id}/challenge"

POST/forms/{id}/upload-request

betaNo auth

fieldIdstringrequired
fileNamestringrequired
mimeTypestringrequired
fileSizeintegerrequired
_hpstring
Honeypot. Send an empty string; any value marks the request as automated.
_wpstring
Second honeypot. Send an empty string.
_costring
Third honeypot. Send an empty string.
_tsinteger
When the form was rendered, in Unix milliseconds.
_tkstring
Built-in bot check: the solved ALTCHA payload for the challenge (provider kanorio).
_ctxstring
What the built-in challenge was issued for: the form id, or customer-login:{siteId}.
captchaTokenstring
Third-party bot check: the token from the provider's widget (provider turnstile, recaptcha or hcaptcha).

curl -X POST "https://{site}/api/v1/forms/{id}/upload-request" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/forms/{id}/submit

betaNo auth

answersobjectrequired
Answers keyed by question id (from GET /forms/{id}).
consent"checked" | "submit_statement"
How the visitor agreed: ticked the consent box, or submitted under a consent statement. Omit when the form asks for no consent.
consentTextIdstring
Id of the consent text the visitor saw (from GET /forms/{id}).
localestring
pagePathstring
Path of the page the form was on, for the submission record.
_hpstring
Honeypot. Send an empty string; any value marks the request as automated.
_wpstring
Second honeypot. Send an empty string.
_costring
Third honeypot. Send an empty string.
_tsinteger
When the form was rendered, in Unix milliseconds.
_tkstring
Built-in bot check: the solved ALTCHA payload for the challenge (provider kanorio).
_ctxstring
What the built-in challenge was issued for: the form id, or customer-login:{siteId}.
captchaTokenstring
Third-party bot check: the token from the provider's widget (provider turnstile, recaptcha or hcaptcha).

curl -X POST "https://{site}/api/v1/forms/{id}/submit" \
  -H "Content-Type: application/json" \
  -d '{}'