Endpoints (forms)

Retrieve all endpoints (forms)

Headers

Name	Type	Description
Authentication	string	Don’t forget to authenticate

[
  {
    "id": "786035271d01882e129295858656324d3e5110ee",
    "reference": "786035271d01882e129295858656324d3e5110ee",
    "title": "Contact form for YourDomain",
    "email": "[email protected]",
    "success_redirect": "https://yourdomain.com/contact-success/",
    "status": "active",
    "disabled_reason": null,
    "created": 1573136139,
    "post_count": 42,
    "post_passed": 40,
    "last_posted": 1573222539
  }
]

Retrieve one endpoint (form)

Headers

Name	Type	Description
Authentication	string	Don’t forget to authenticate

{
  "reference": "786035271d01882e129295858656324d3e5110ee",
  "title": "Contact form for YourDomain",
  "email": "[email protected]",
  "status": "active",
  "disabled_reason": null,
  "success_redirect": "https://yourdomain.com/contact-success/",
  "reply_to_field": "email",
  "recaptcha_mode": "default",
  "captcha_provider": "recaptcha",
  "captcha_site_key": "",
  "footer_enabled": true,
  "honeypot_field": "",
  "auto_response_enabled": true,
  "auto_response_subject": "Thanks for reaching out, {{name}}!",
  "auto_response_body": "Hi {{name}},\n\nThanks for reaching out. We will get back to you soon.",
  "auto_response_from_name": "YourDomain",
  "created": 1573136139,
  "last_posted": 1573222539,
  "post_count": 42,
  "last_passed": 1573222539,
  "post_passed": 40,
  "file_uploads_enabled": false
}

A few fields worth calling out:

• status: active while the endpoint accepts submissions. disabled means it has been closed and no longer accepts them. new is a form that has not been activated yet.
• disabled_reason: why a closed endpoint was closed, and with it what the way back is. See the table below.
• recaptcha_mode: whether captcha runs on Un-static’s own keys (default), is turned off (off), or uses your own secret (custom).
• captcha_provider: which vendor is used when captcha is on: recaptcha, turnstile, or hcaptcha.
• reply_to_field: the name of the submitted field holding the visitor’s e-mail address. This is the prerequisite for the auto-response below.
• auto_response_enabled, auto_response_subject, auto_response_body, auto_response_from_name: the automatic confirmation e-mail sent back to whoever submits the form. See Send an Auto-Response Confirmation Email to Form Submitters for setup and placeholder behavior.
• file_uploads_enabled: whether your account’s plan allows file uploads on this form.

Why an endpoint is disabled

An endpoint that has been closed reads "status": "disabled" whatever closed it, so disabled_reason is what tells the cases apart.

disabled_reason	What happened	Getting the endpoint back
null	Nothing closed it automatically. Either the endpoint is fine and status is active, or it was disabled by hand by our support team.	Nothing to do when status is active. When it is disabled, reply to the mail we sent you or get in touch.
dead_notify_address	The notification address on the endpoint is dead, and the endpoint is not attached to an account we can reach. Mail to it hard bounced, nothing has been delivered for months, and a fresh check agreed.	Get in touch and we will reopen it once there is a working address on it.
dead_notify_address_linked	The endpoint is paused, which is what your dashboard calls it too. Same dead notification address, but this endpoint belongs to your account: we mailed you about it, waited fourteen days, and the address was still dead.	Yours to fix, two ways. Get the mailbox accepting mail again and press “Reopen this form” on the endpoint’s page. Or point the endpoint at an address that accepts mail, which reopens it by itself, no second step. Either way the submissions that were waiting are resent.
erasure	The account the endpoint belongs to is being deleted. Endpoints are closed first so no submission is lost part way through.	Only reachable if the deletion was called off or did not finish. Get in touch.

Treat this as a read-only field. You cannot set it, and the way to close an endpoint yourself stays what it always was: delete it.

What a visitor gets while an endpoint is closed depends on which leg they submit through, and it does not line up one-to-one with disabled_reason:

• The AJAX endpoint answers 410 with "result": "form-paused" for dead_notify_address_linked and "result": "form-disabled" for dead_notify_address. For every other closed endpoint, a staff disable or an erasure closure included, it answers the same deliberately vague 404 "unknown-form" an unrecognised reference gets.
• A plain browser form post never gets a 410. For those same two dead-address closures it redirects to a submission-failed page that explains the endpoint is paused or closed; anything else closed is a 404.

GET /api/forms/{reference} returns a 404 when the reference does not exist, and a 403 with {"error": "Unauthorized"} when the form belongs to another account.

Update an endpoint (form)

This is a partial update: only the keys present in the request body are changed, everything else is left as-is.

{
  "reply_to_field": "email",
  "auto_response_enabled": true,
  "auto_response_subject": "Thanks for reaching out, {{name}}!",
  "auto_response_body": "Hi {{name}},\n\nThanks for reaching out. We will get back to you soon.",
  "auto_response_from_name": "YourDomain"
}

Accepted fields

Name	Type	Description
title	string	The form’s display name.
success_redirect	string	URL the visitor is redirected to after a successful submission.
reply_to_field	string	Name of the submitted field holding the visitor’s e-mail address; also the prerequisite for the auto-response.
honeypot_field	string	Name of the honeypot field used for spam filtering.
footer_enabled	bool	Whether the Un-static branding footer is included in the notification e-mail you receive for each submission.
captcha_provider	string	One of off, recaptcha, turnstile, hcaptcha.
recaptcha_secret	string	"off" disables captcha. "" (empty string) switches to Un-static’s own keys. Any other value sets your own secret. Setting a secret on a captcha-disabled form re-enables captcha, defaulting to the recaptcha provider unless captcha_provider is sent in the same request.
captcha_site_key	string	Max 255 characters; letters, digits, dots, dashes, and underscores only. Only valid together with your own captcha secret; returns a 422 otherwise.
auto_response_enabled	bool	Whether the auto-response e-mail is sent to submitters.
auto_response_subject	string	Max 200 characters. Accepts {{field}} placeholders.
auto_response_body	string	Max 5000 characters, plain text. Accepts {{field}} placeholders.
auto_response_from_name	string	Max 60 characters. The sender name shown to the visitor; the mail itself is always sent from [email protected].

{
  "reference": "786035271d01882e129295858656324d3e5110ee",
  "title": "Contact form for YourDomain",
  "status": "active",
  "disabled_reason": null,
  "success_redirect": "https://yourdomain.com/contact-success/",
  "reply_to_field": "email",
  "recaptcha_mode": "default",
  "captcha_provider": "recaptcha",
  "captcha_site_key": "",
  "footer_enabled": true,
  "honeypot_field": "",
  "auto_response_enabled": true,
  "auto_response_subject": "Thanks for reaching out, {{name}}!",
  "auto_response_body": "Hi {{name}},\n\nThanks for reaching out. We will get back to you soon.",
  "auto_response_from_name": "YourDomain"
}

{
  "error": "validation_failed",
  "fields": {
    "captcha_site_key": "requires your own captcha secret (recaptcha_secret)"
  }
}

PUT /api/forms/{reference} returns the same 404 and 403 shapes as the GET endpoint above.

The echo carries status and disabled_reason, so an update to a closed endpoint tells you it is closed and why without a follow-up GET. Note that this endpoint cannot change the notification address, so it cannot reopen a paused endpoint either: repointing is done from your dashboard.