Sign Customiser

Navigation

Dark mode

Customiser forms

Create a form

Copy page

Adds a form to the customiser, at the end of the current presentation order. name and form_type are required; every other property has a documented default (no receivers, save_customer_details false, post_submission_action default, and one required customer Email field). fields is the form's field document.

POST/api/v3/customisers/{customiser_id}/forms
POSTCreate a form
POST/api/v3/customisers/{customiser_id}/forms

Create a form

Adds a form to the customiser, at the end of the current presentation order. `name` and `form_type` are required; every other property has a documented default (no receivers, `save_customer_details` false, `post_submission_action` default, and one required customer Email field). `fields` is the form's field document. Each field names the input it renders as, and only the properties that input reads: a `min` on a text field, or `options` on anything but a dropdown or multiple-choice field, is a 422 `field_not_used_by_input_type` on the offending property. Identities (`field_id`, `option_id`) are generated when omitted; send them back unchanged to keep a field's existing submissions attached to it. Every form keeps one required Email field assigned to the customer email. If `fields` omits it, the API promotes an existing Email field or adds one. Requires `customisers:write` and an `Idempotency-Key`. The write clears the customiser's cached storefront configuration and runs the advisory language sync, which is what translates the form's copy into the customiser's other languages. It never regenerates Shopify products, product images, or the product cache, so live listings are untouched. Option writes also spend one unit of a separate per-key option-write budget; exhausting it returns a 429 with `retry_after`.

Authorisation

The Authorization header expects a Bearer token. Generate one on the API keys page in your dashboard.

Path

The customiser id, from the list customisers operation.

Bodyapplication/json
Create a form

Overview

Each field names the input it renders as, and only the properties that input reads: a min on a text field, or options on anything but a dropdown or multiple-choice field, is a 422 field_not_used_by_input_type on the offending property. Identities (field_id, option_id) are generated when omitted; send them back unchanged to keep a field's existing submissions attached to it. Every form keeps one required Email field assigned to the customer email. If fields omits it, the API promotes an existing Email field or adds one. Requires customisers:write and an Idempotency-Key. The write clears the customiser's cached storefront configuration and runs the advisory language sync, which is what translates the form's copy into the customiser's other languages. It never regenerates Shopify products, product images, or the product cache, so live listings are untouched. Option writes also spend one unit of a separate per-key option-write budget; exhausting it returns a 429 with retry_after.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id.

Example: 1

Request body

form_typestringbody
post_submission_actionstringbody
fieldsarraybody
namestringbody
descriptionstringbody
button_labelstringbody
subjectstringbody
recipient_emailsarraybody
save_customer_detailsbooleanbody
redirect_urlstringbody

Request body example

application/json
{
  "form_type": "quote",
  "post_submission_action": "default",
  "fields": [
    {
      "name": "Email",
      "input_type": "email",
      "customer_field": "email",
      "required": true,
      "reply_to": true,
      "options": [
        {
          "label": null,
          "value": null
        }
      ]
    }
  ],
  "name": "Request a quote",
  "description": "Tell us about your project",
  "button_label": "Send",
  "subject": "New quote request",
  "recipient_emails": [
    "sales@example.com"
  ],
  "save_customer_details": true,
  "redirect_url": "https://example.com/thank-you"
}
Create a form
curl https://web.signcustomiser.com/api/v3/customisers/1/forms \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "form_type": "quote",
  "post_submission_action": "default",
  "fields": [
    {
      "name": "Email",
      "input_type": "email",
      "customer_field": "email",
      "required": true,
      "reply_to": true,
      "options": [
        {
          "label": null,
          "value": null
        }
      ]
    }
  ],
  "name": "Request a quote",
  "description": "Tell us about your project",
  "button_label": "Send",
  "subject": "New quote request",
  "recipient_emails": [
    "sales@example.com"
  ],
  "save_customer_details": true,
  "redirect_url": "https://example.com/thank-you"
}'
Response
{
  "data": {
    "object": "form",
    "id": 7,
    "customiser_id": 42,
    "name": "Request a quote",
    "description": null,
    "form_type": "quote",
    "button_label": null,
    "subject": null,
    "recipient_emails": [],
    "save_customer_details": false,
    "post_submission_action": "default",
    "redirect_url": null,
    "emails_enabled": true,
    "suppressed_emails": [],
    "fields": [
      {
        "field_id": "3f2a9c1e-5d6b-4a7c-8e9f-0a1b2c3d4e5f",
        "name": "Email",
        "input_type": "email",
        "required": true,
        "customer_field": "email",
        "info": null,
        "placeholder": null,
        "checkbox_value": null,
        "min": null,
        "max": null,
        "min_date": null,
        "max_date": null,
        "allow_multiple": false,
        "reply_to": true,
        "options": []
      }
    ],
    "sort_order": 1,
    "created_at": "2026-08-14T00:00:00Z",
    "updated_at": "2026-08-14T00:00:00Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/forms/7",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

Type a question and press Enter. Use the arrow keys to move between the results.