curl --request POST \
--url https://apix.spotzee.com/api/client/form-definitions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"type": "subscription_opt_in",
"settings": {
"settings_version": 1,
"subscriptions": [
{
"id": 123,
"name": "<string>",
"channel": "email"
}
],
"fields": [
{
"kind": "builtin",
"label": "<string>",
"required": true
}
],
"layout": {
"delay_seconds": 1,
"page_targeting_notes": "<string>",
"dismiss_frequency": "<string>",
"mobile_behaviour": "<string>"
},
"website_url": "<string>",
"success_message": "<string>",
"error_message": "<string>"
}
}
'import requests
url = "https://apix.spotzee.com/api/client/form-definitions"
payload = {
"name": "<string>",
"type": "subscription_opt_in",
"settings": {
"settings_version": 1,
"subscriptions": [
{
"id": 123,
"name": "<string>",
"channel": "email"
}
],
"fields": [
{
"kind": "builtin",
"label": "<string>",
"required": True
}
],
"layout": {
"delay_seconds": 1,
"page_targeting_notes": "<string>",
"dismiss_frequency": "<string>",
"mobile_behaviour": "<string>"
},
"website_url": "<string>",
"success_message": "<string>",
"error_message": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
type: 'subscription_opt_in',
settings: {
settings_version: 1,
subscriptions: [{id: 123, name: '<string>', channel: 'email'}],
fields: [{kind: 'builtin', label: '<string>', required: true}],
layout: {
delay_seconds: 1,
page_targeting_notes: '<string>',
dismiss_frequency: '<string>',
mobile_behaviour: '<string>'
},
website_url: '<string>',
success_message: '<string>',
error_message: '<string>'
}
})
};
fetch('https://apix.spotzee.com/api/client/form-definitions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apix.spotzee.com/api/client/form-definitions"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"type\": \"subscription_opt_in\",\n \"settings\": {\n \"settings_version\": 1,\n \"subscriptions\": [\n {\n \"id\": 123,\n \"name\": \"<string>\",\n \"channel\": \"email\"\n }\n ],\n \"fields\": [\n {\n \"kind\": \"builtin\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"layout\": {\n \"delay_seconds\": 1,\n \"page_targeting_notes\": \"<string>\",\n \"dismiss_frequency\": \"<string>\",\n \"mobile_behaviour\": \"<string>\"\n },\n \"website_url\": \"<string>\",\n \"success_message\": \"<string>\",\n \"error_message\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": 123,
"project_id": 123,
"public_token": "<string>",
"name": "<string>",
"type": "subscription_opt_in",
"status": "draft",
"settings": {
"settings_version": 1,
"subscriptions": [
{
"id": 123,
"name": "<string>",
"channel": "email"
}
],
"fields": [
{
"kind": "builtin",
"key": "email",
"label": "<string>",
"required": true
}
],
"layout": {
"display_type": "inline",
"delay_seconds": 1,
"page_targeting_notes": "<string>",
"dismiss_frequency": "<string>",
"mobile_behaviour": "<string>"
},
"website_url": "<string>",
"success_message": "<string>",
"error_message": "<string>"
},
"created_at": "<string>",
"updated_at": "<string>",
"deleted_at": "<string>"
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}Create a form definition
Creates a saved project-scoped form definition from structured settings.
Idempotent — pass an Idempotency-Key header to make safely retryable. On a replay the original response is returned with Idempotent-Replayed: true. See the API conventions guide for the full state machine, TTL, and mismatch behaviour.
curl --request POST \
--url https://apix.spotzee.com/api/client/form-definitions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"type": "subscription_opt_in",
"settings": {
"settings_version": 1,
"subscriptions": [
{
"id": 123,
"name": "<string>",
"channel": "email"
}
],
"fields": [
{
"kind": "builtin",
"label": "<string>",
"required": true
}
],
"layout": {
"delay_seconds": 1,
"page_targeting_notes": "<string>",
"dismiss_frequency": "<string>",
"mobile_behaviour": "<string>"
},
"website_url": "<string>",
"success_message": "<string>",
"error_message": "<string>"
}
}
'import requests
url = "https://apix.spotzee.com/api/client/form-definitions"
payload = {
"name": "<string>",
"type": "subscription_opt_in",
"settings": {
"settings_version": 1,
"subscriptions": [
{
"id": 123,
"name": "<string>",
"channel": "email"
}
],
"fields": [
{
"kind": "builtin",
"label": "<string>",
"required": True
}
],
"layout": {
"delay_seconds": 1,
"page_targeting_notes": "<string>",
"dismiss_frequency": "<string>",
"mobile_behaviour": "<string>"
},
"website_url": "<string>",
"success_message": "<string>",
"error_message": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
type: 'subscription_opt_in',
settings: {
settings_version: 1,
subscriptions: [{id: 123, name: '<string>', channel: 'email'}],
fields: [{kind: 'builtin', label: '<string>', required: true}],
layout: {
delay_seconds: 1,
page_targeting_notes: '<string>',
dismiss_frequency: '<string>',
mobile_behaviour: '<string>'
},
website_url: '<string>',
success_message: '<string>',
error_message: '<string>'
}
})
};
fetch('https://apix.spotzee.com/api/client/form-definitions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apix.spotzee.com/api/client/form-definitions"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"type\": \"subscription_opt_in\",\n \"settings\": {\n \"settings_version\": 1,\n \"subscriptions\": [\n {\n \"id\": 123,\n \"name\": \"<string>\",\n \"channel\": \"email\"\n }\n ],\n \"fields\": [\n {\n \"kind\": \"builtin\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"layout\": {\n \"delay_seconds\": 1,\n \"page_targeting_notes\": \"<string>\",\n \"dismiss_frequency\": \"<string>\",\n \"mobile_behaviour\": \"<string>\"\n },\n \"website_url\": \"<string>\",\n \"success_message\": \"<string>\",\n \"error_message\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": 123,
"project_id": 123,
"public_token": "<string>",
"name": "<string>",
"type": "subscription_opt_in",
"status": "draft",
"settings": {
"settings_version": 1,
"subscriptions": [
{
"id": 123,
"name": "<string>",
"channel": "email"
}
],
"fields": [
{
"kind": "builtin",
"key": "email",
"label": "<string>",
"required": true
}
],
"layout": {
"display_type": "inline",
"delay_seconds": 1,
"page_targeting_notes": "<string>",
"dismiss_frequency": "<string>",
"mobile_behaviour": "<string>"
},
"website_url": "<string>",
"success_message": "<string>",
"error_message": "<string>"
},
"created_at": "<string>",
"updated_at": "<string>",
"deleted_at": "<string>"
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}Authorizations
Project-scoped secret API key (sk_…). Pass in the Authorization: Bearer <key> header. Grants access to the project the key was issued for.
Body
1Form definition type. V1 enables subscription opt-in forms only.
subscription_opt_in "subscription_opt_in"
Hide child attributes
Hide child attributes
1 Hide child attributes
Hide child attributes
inline, timed_popup, floating_bar, slide_in, welcome_mat x >= 0Lifecycle status for a saved form definition.
draft, active, archived "draft"
Response
The created form definition.
A saved project-scoped form-builder definition. Generated prompt text is derived from settings.
Form definition type. V1 enables subscription opt-in forms only.
subscription_opt_in "subscription_opt_in"
Lifecycle status for a saved form definition.
draft, active, archived "draft"
Hide child attributes
Hide child attributes
1 Hide child attributes
Hide child attributes
inline, timed_popup, floating_bar, slide_in, welcome_mat x >= 0Was this page helpful?