Forms
Hosted signup forms with double opt-in, embed code and submissions.
List signup forms
GET /v1/forms
Each form includes submission and confirmation counts and its public URLs.
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"data": [{
"id": string,
"object": "form",
"name": string,
"status": "active" | "disabled",
"fields": [{ … }],
"listIds": [string],
"consentText": string or null,
"consentVersion": number,
"doubleOptIn": boolean,
"successMessage": string or null,
"redirectUrl": string or null,
"fromName": string or null,
"fromEmail": string or null,
"replyTo": string or null,
"confirmation": {
"subject": string,
"heading": string,
"body": string,
"buttonLabel": string
},
"welcomeTemplateId": string or null,
"style": {
"primary": string,
"background": string,
"text": string,
"font": string,
"logoUrl": string,
"title": string,
"description": string,
"buttonLabel": string,
"useBrand": boolean
},
"allowedOrigins": [string],
"stats": {
"submissions": number,
"confirmations": number,
"pending": number,
"confirmationRate": number or null
},
"urls": {
"hosted": string,
"submit": string,
"script": string
},
"createdAt": string,
"updatedAt": string
}],
"nextCursor": string or null
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Create a signup form
POST /v1/forms
Double opt-in is on unless doubleOptIn: false. The response includes the hosted page URL; GET /v1/forms/{id}/embed returns the embed code.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
namerequired | string | |
status | "active" | "disabled" | |
fields | array of object | At most 20 items. |
fields[].keyrequired | string | Contact attribute key (first_name, company, …). email is always present and is not listed here. |
fields[].labelrequired | string | |
fields[].type | "text" | "number" | "date" | "boolean" | "category" | "email" | Default "text". |
fields[].required | boolean | |
fields[].placeholder | string or null | |
fields[].options | array of string or null | Choices for category fields. At most 50 items. |
listIds | array of string | Lists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items. |
consentText | string or null | Shown next to a required checkbox. Changing it starts a new consent version. |
doubleOptIn | boolean | Default true: new contacts stay pending until they confirm by email. |
successMessage | string or null | |
redirectUrl | string (uri) or null | After a successful submit, go here instead of showing the success message (http or https). |
fromName | string or null | |
fromEmail | string (email) or null | Sender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain. |
replyTo | string (email) or null | |
confirmation | object or null | |
confirmation.subject | string | |
confirmation.heading | string | |
confirmation.body | string | Plain text; blank lines separate paragraphs. {{ form_name }} and {{ workspace_name }} are available. |
confirmation.buttonLabel | string | |
welcomeTemplateId | string or null | Template sent once the contact is subscribed. |
style | object | |
style.primary | string | |
style.background | string | |
style.text | string | |
style.font | string | |
style.logoUrl | string | |
style.title | string | |
style.description | string | |
style.buttonLabel | string | |
style.useBrand | boolean | Use the workspace brand (logo, colors, font) for values not set here. Default true. |
allowedOrigins | array of string | Websites allowed to post this form (for example https://www.example.com). Empty: any site. At most 20 items. |
Responses
{
"id": string,
"object": "form",
"name": string,
"status": "active" | "disabled",
"fields": [{
"key": string,
"label": string,
"type": "text" | "number" | "date" | "boolean" | "category" | "email",
"required": boolean,
"placeholder": string or null,
"options": [string] or null
}],
"listIds": [string],
"consentText": string or null,
"consentVersion": number,
"doubleOptIn": boolean,
"successMessage": string or null,
"redirectUrl": string or null,
"fromName": string or null,
"fromEmail": string or null,
"replyTo": string or null,
"confirmation": {
"subject": string,
"heading": string,
"body": string,
"buttonLabel": string
},
"welcomeTemplateId": string or null,
"style": {
"primary": string,
"background": string,
"text": string,
"font": string,
"logoUrl": string,
"title": string,
"description": string,
"buttonLabel": string,
"useBrand": boolean
},
"allowedOrigins": [string],
"stats": {
"submissions": number,
"confirmations": number,
"pending": number,
"confirmationRate": number or null
},
"urls": {
"hosted": string,
"submit": string,
"script": string
},
"createdAt": string,
"updatedAt": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Preview a form
POST /v1/forms/preview
The hosted page HTML for unsaved settings (for a live preview). Nothing is stored.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
name | string | |
status | "active" | "disabled" | |
fields | array of object | At most 20 items. |
fields[].keyrequired | string | Contact attribute key (first_name, company, …). email is always present and is not listed here. |
fields[].labelrequired | string | |
fields[].type | "text" | "number" | "date" | "boolean" | "category" | "email" | Default "text". |
fields[].required | boolean | |
fields[].placeholder | string or null | |
fields[].options | array of string or null | Choices for category fields. At most 50 items. |
listIds | array of string | Lists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items. |
consentText | string or null | Shown next to a required checkbox. Changing it starts a new consent version. |
doubleOptIn | boolean | Default true: new contacts stay pending until they confirm by email. |
successMessage | string or null | |
redirectUrl | string (uri) or null | After a successful submit, go here instead of showing the success message (http or https). |
fromName | string or null | |
fromEmail | string (email) or null | Sender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain. |
replyTo | string (email) or null | |
confirmation | object or null | |
confirmation.subject | string | |
confirmation.heading | string | |
confirmation.body | string | Plain text; blank lines separate paragraphs. {{ form_name }} and {{ workspace_name }} are available. |
confirmation.buttonLabel | string | |
welcomeTemplateId | string or null | Template sent once the contact is subscribed. |
style | object | |
style.primary | string | |
style.background | string | |
style.text | string | |
style.font | string | |
style.logoUrl | string | |
style.title | string | |
style.description | string | |
style.buttonLabel | string | |
style.useBrand | boolean | Use the workspace brand (logo, colors, font) for values not set here. Default true. |
allowedOrigins | array of string | Websites allowed to post this form (for example https://www.example.com). Empty: any site. At most 20 items. |
Responses
{
"html": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Get a signup form
GET /v1/forms/{id}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "form",
"name": string,
"status": "active" | "disabled",
"fields": [{
"key": string,
"label": string,
"type": "text" | "number" | "date" | "boolean" | "category" | "email",
"required": boolean,
"placeholder": string or null,
"options": [string] or null
}],
"listIds": [string],
"consentText": string or null,
"consentVersion": number,
"doubleOptIn": boolean,
"successMessage": string or null,
"redirectUrl": string or null,
"fromName": string or null,
"fromEmail": string or null,
"replyTo": string or null,
"confirmation": {
"subject": string,
"heading": string,
"body": string,
"buttonLabel": string
},
"welcomeTemplateId": string or null,
"style": {
"primary": string,
"background": string,
"text": string,
"font": string,
"logoUrl": string,
"title": string,
"description": string,
"buttonLabel": string,
"useBrand": boolean
},
"allowedOrigins": [string],
"stats": {
"submissions": number,
"confirmations": number,
"pending": number,
"confirmationRate": number or null
},
"urls": {
"hosted": string,
"submit": string,
"script": string
},
"createdAt": string,
"updatedAt": string
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Update a signup form
PATCH /v1/forms/{id}
Changing consentText increases consentVersion; consent proof records the version each contact agreed to.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
name | string | |
status | "active" | "disabled" | |
fields | array of object | At most 20 items. |
fields[].keyrequired | string | Contact attribute key (first_name, company, …). email is always present and is not listed here. |
fields[].labelrequired | string | |
fields[].type | "text" | "number" | "date" | "boolean" | "category" | "email" | Default "text". |
fields[].required | boolean | |
fields[].placeholder | string or null | |
fields[].options | array of string or null | Choices for category fields. At most 50 items. |
listIds | array of string | Lists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items. |
consentText | string or null | Shown next to a required checkbox. Changing it starts a new consent version. |
doubleOptIn | boolean | Default true: new contacts stay pending until they confirm by email. |
successMessage | string or null | |
redirectUrl | string (uri) or null | After a successful submit, go here instead of showing the success message (http or https). |
fromName | string or null | |
fromEmail | string (email) or null | Sender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain. |
replyTo | string (email) or null | |
confirmation | object or null | |
confirmation.subject | string | |
confirmation.heading | string | |
confirmation.body | string | Plain text; blank lines separate paragraphs. {{ form_name }} and {{ workspace_name }} are available. |
confirmation.buttonLabel | string | |
welcomeTemplateId | string or null | Template sent once the contact is subscribed. |
style | object | |
style.primary | string | |
style.background | string | |
style.text | string | |
style.font | string | |
style.logoUrl | string | |
style.title | string | |
style.description | string | |
style.buttonLabel | string | |
style.useBrand | boolean | Use the workspace brand (logo, colors, font) for values not set here. Default true. |
allowedOrigins | array of string | Websites allowed to post this form (for example https://www.example.com). Empty: any site. At most 20 items. |
Responses
{
"id": string,
"object": "form",
"name": string,
"status": "active" | "disabled",
"fields": [{
"key": string,
"label": string,
"type": "text" | "number" | "date" | "boolean" | "category" | "email",
"required": boolean,
"placeholder": string or null,
"options": [string] or null
}],
"listIds": [string],
"consentText": string or null,
"consentVersion": number,
"doubleOptIn": boolean,
"successMessage": string or null,
"redirectUrl": string or null,
"fromName": string or null,
"fromEmail": string or null,
"replyTo": string or null,
"confirmation": {
"subject": string,
"heading": string,
"body": string,
"buttonLabel": string
},
"welcomeTemplateId": string or null,
"style": {
"primary": string,
"background": string,
"text": string,
"font": string,
"logoUrl": string,
"title": string,
"description": string,
"buttonLabel": string,
"useBrand": boolean
},
"allowedOrigins": [string],
"stats": {
"submissions": number,
"confirmations": number,
"pending": number,
"confirmationRate": number or null
},
"urls": {
"hosted": string,
"submit": string,
"script": string
},
"createdAt": string,
"updatedAt": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Delete a signup form
DELETE /v1/forms/{id}
Contacts who signed up are kept. Pending confirmation links stop working.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Embed code for a form
GET /v1/forms/{id}/embed
html is a plain HTML form that works without JavaScript. Add script after it to show the result in place instead of on the hosted page.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"hostedUrl": string,
"html": string,
"script": string,
"htmlWithScript": string
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
List form submissions
GET /v1/forms/{id}/submissions
Newest first. Filter by status (comma-separated): pending, confirmed, subscribed, already_subscribed, rejected.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
status | query | string | |
limit | query | integer | Default 100. 1 to 500. |
Responses
{
"data": [{
"id": string,
"object": "form_submission",
"formId": string,
"contactId": string or null,
"email": string,
"status": "pending" | "confirmed" | "subscribed" | "already_subscribed" | "rejected",
"consentVersion": number or null,
"createdAt": string,
"confirmedAt": string or null,
"confirmationError": {
"code": string,
"message": string,
"at": string
}
}],
"nextCursor": string or null
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Submit a form from your server
POST /v1/forms/{id}/submissions
Same rules as the hosted form: with double opt-in the contact is pending until they confirm by email. Pass the subscriber’s ip and userAgent to include them in the consent proof (the IP is stored only as a hash).
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) | |
firstName | string | |
lastName | string | |
attributes | object | Values for the form fields, by attribute key. |
consent | boolean | Required (true) when the form has consent text. |
ip | string | The subscriber’s IP address, stored only as a hash in the consent proof. |
userAgent | string |
Responses
{
"status": "pending" | "subscribed" | "already_subscribed" | "ignored",
"submissionId": string or null
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)