## Retrieve all endpoints (forms)

`GET https://forms.un-static.com/api/forms`

**Headers**

| Name | Type | Description |
| --- | --- | --- |
| Authentication | string | Don't forget to authenticate |

```json title="200"
[
  {
    "id": "786035271d01882e129295858656324d3e5110ee",
    "reference": "786035271d01882e129295858656324d3e5110ee",
    "title": "Contact form for YourDomain",
    "email": "you@yourdomain.com",
    "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)

`GET https://forms.un-static.com/api/forms/{reference}`

**Headers**

| Name | Type | Description |
| --- | --- | --- |
| Authentication | string | Don't forget to authenticate |

```json title="200"
{
  "reference": "786035271d01882e129295858656324d3e5110ee",
  "title": "Contact form for YourDomain",
  "email": "you@yourdomain.com",
  "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](/how-to/add-auto-response-confirmation-email/) 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](/contact/). |
| `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](/contact/) 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](/contact/). |

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)

`PUT https://forms.un-static.com/api/forms/{reference}`

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

```json title="Request"
{
  "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 `forms@un-static.com`. |

```json title="200"
{
  "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"
}
```

```json title="422"
{
  "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.