Docs / API reference

Forms

Hosted signup forms with double opt-in, embed code and submissions.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

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

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
namerequiredstring
status"active" | "disabled"
fieldsarray of objectAt most 20 items.
fields[].keyrequiredstringContact attribute key (first_name, company, …). email is always present and is not listed here.
fields[].labelrequiredstring
fields[].type"text" | "number" | "date" | "boolean" | "category" | "email"Default "text".
fields[].requiredboolean
fields[].placeholderstring or null
fields[].optionsarray of string or nullChoices for category fields. At most 50 items.
listIdsarray of stringLists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items.
consentTextstring or nullShown next to a required checkbox. Changing it starts a new consent version.
doubleOptInbooleanDefault true: new contacts stay pending until they confirm by email.
successMessagestring or null
redirectUrlstring (uri) or nullAfter a successful submit, go here instead of showing the success message (http or https).
fromNamestring or null
fromEmailstring (email) or nullSender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain.
replyTostring (email) or null
confirmationobject or null
confirmation.subjectstring
confirmation.headingstring
confirmation.bodystringPlain text; blank lines separate paragraphs. {{ form_name }} and {{ workspace_name }} are available.
confirmation.buttonLabelstring
welcomeTemplateIdstring or nullTemplate sent once the contact is subscribed.
styleobject
style.primarystring
style.backgroundstring
style.textstring
style.fontstring
style.logoUrlstring
style.titlestring
style.descriptionstring
style.buttonLabelstring
style.useBrandbooleanUse the workspace brand (logo, colors, font) for values not set here. Default true.
allowedOriginsarray of stringWebsites allowed to post this form (for example https://www.example.com). Empty: any site. At most 20 items.

Responses

201 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
namestring
status"active" | "disabled"
fieldsarray of objectAt most 20 items.
fields[].keyrequiredstringContact attribute key (first_name, company, …). email is always present and is not listed here.
fields[].labelrequiredstring
fields[].type"text" | "number" | "date" | "boolean" | "category" | "email"Default "text".
fields[].requiredboolean
fields[].placeholderstring or null
fields[].optionsarray of string or nullChoices for category fields. At most 50 items.
listIdsarray of stringLists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items.
consentTextstring or nullShown next to a required checkbox. Changing it starts a new consent version.
doubleOptInbooleanDefault true: new contacts stay pending until they confirm by email.
successMessagestring or null
redirectUrlstring (uri) or nullAfter a successful submit, go here instead of showing the success message (http or https).
fromNamestring or null
fromEmailstring (email) or nullSender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain.
replyTostring (email) or null
confirmationobject or null
confirmation.subjectstring
confirmation.headingstring
confirmation.bodystringPlain text; blank lines separate paragraphs. {{ form_name }} and {{ workspace_name }} are available.
confirmation.buttonLabelstring
welcomeTemplateIdstring or nullTemplate sent once the contact is subscribed.
styleobject
style.primarystring
style.backgroundstring
style.textstring
style.fontstring
style.logoUrlstring
style.titlestring
style.descriptionstring
style.buttonLabelstring
style.useBrandbooleanUse the workspace brand (logo, colors, font) for values not set here. Default true.
allowedOriginsarray of stringWebsites allowed to post this form (for example https://www.example.com). Empty: any site. At most 20 items.

Responses

200 Success

{
  "html": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Get a signup form

GET /v1/forms/{id}

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestring
status"active" | "disabled"
fieldsarray of objectAt most 20 items.
fields[].keyrequiredstringContact attribute key (first_name, company, …). email is always present and is not listed here.
fields[].labelrequiredstring
fields[].type"text" | "number" | "date" | "boolean" | "category" | "email"Default "text".
fields[].requiredboolean
fields[].placeholderstring or null
fields[].optionsarray of string or nullChoices for category fields. At most 50 items.
listIdsarray of stringLists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items.
consentTextstring or nullShown next to a required checkbox. Changing it starts a new consent version.
doubleOptInbooleanDefault true: new contacts stay pending until they confirm by email.
successMessagestring or null
redirectUrlstring (uri) or nullAfter a successful submit, go here instead of showing the success message (http or https).
fromNamestring or null
fromEmailstring (email) or nullSender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain.
replyTostring (email) or null
confirmationobject or null
confirmation.subjectstring
confirmation.headingstring
confirmation.bodystringPlain text; blank lines separate paragraphs. {{ form_name }} and {{ workspace_name }} are available.
confirmation.buttonLabelstring
welcomeTemplateIdstring or nullTemplate sent once the contact is subscribed.
styleobject
style.primarystring
style.backgroundstring
style.textstring
style.fontstring
style.logoUrlstring
style.titlestring
style.descriptionstring
style.buttonLabelstring
style.useBrandbooleanUse the workspace brand (logo, colors, font) for values not set here. Default true.
allowedOriginsarray of stringWebsites allowed to post this form (for example https://www.example.com). Empty: any site. At most 20 items.

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
idrequiredpathstring

Responses

204 No content

Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "hostedUrl": string,
  "html": string,
  "script": string,
  "htmlWithScript": string
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
idrequiredpathstring
statusquerystring
limitqueryintegerDefault 100. 1 to 500.

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
emailrequiredstring (email)
firstNamestring
lastNamestring
attributesobjectValues for the form fields, by attribute key.
consentbooleanRequired (true) when the form has consent text.
ipstringThe subscriber’s IP address, stored only as a hash in the consent proof.
userAgentstring

Responses

202 Success

{
  "status": "pending" | "subscribed" | "already_subscribed" | "ignored",
  "submissionId": string or null
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)