Skip to content
Content SnareHelp centre

API: create a request with fields

Quick answer

Send one POST call to /partner_api/v1/requests to create a complete request, with its pages, sections and questions built inline. You don't need a saved template. New requests start as drafts and don't reach the client until you set status to published.

One call to this endpoint creates a complete request and builds its pages, sections, and fields inline, so you can turn your own data or AI output into a ready-to-send request without a saved template.

API access is off by default on every account, whatever your plan, so you turn it on before any token will work. See Get started with the API.

This endpoint is in alpha and is not guaranteed to stay backwards compatible, so check for changes before you build production systems against it.

Endpoint and scopes

The endpoint is POST /partner_api/v1/requests. Authorize it with an OAuth token or a personal access token. Either one needs the write_requests scope, and an OAuth token can have the broader write instead. Add write_clients if the call might create a new client; without it the call returns 401 before anything is built.

Top-level properties

Three properties are always required: name, pages_data, and a way to identify the client. The simplest is client_email. You can also pass client_id for a client you already have, which skips the new-client handling below. When client_email belongs to a client you do not already have, client_full_name is required too, and your token needs the write_clients scope. Everything else is optional.

Property Type Required What it does
name string Yes The request name.
client_email string Yes Email address of the client this request is for.
client_full_name string For a new client Full name, used when the request has to create a new client.
client_phone string No Phone number for a new client.
company_name string No Company name for the client.
folder_name string No Folder to file the request under.
due string No Due date, as yyyy-mm-dd.
status string No draft (the default) or published.
owner_id string No Team member ID to own the request.
owner_email string No Team member email to own the request, instead of owner_id.
communication_template_id string No ID of a reminder scheduleThe shared set of automated emails and text messages Content Snare sends about a request. to attach.
communication_template_name string No Name of a reminder schedule, instead of the ID.
comments_enabled true or false No Let the client leave comments.
passcode_enabled true or false No Require a PIN to open the request.
share_via_link_enabled true or false No Let the client share the request by link.
pages_data array Yes The pages, sections, and questions to build.

Pages, sections, and questions

You build the request from pages_data, an array of pages. Every page needs a name and a sections_data array. Every section needs a name and a questions_data array. Every question takes the keys in the table below. A page is a tab the client moves between, a section groups questions under a heading, and a question is a single field.

Request
├── Page 1
│   ├── Section A
│   │   ├── Question 1
│   │   └── Question 2
│   └── Section B
│       └── Question 3
└── Page 2
    └── Section C
        └── Question 4

Each question object takes these keys:

Key Required What it does
question Yes The label the client sees.
data_type Yes The field type. See Field types below.
question_number Yes A number that identifies the question.
options For choice types The choices the client picks from.
columns For tables The table's column headings.
instructions No Help text shown with the field.
show_when No Conditional visibility rules.

Every question_number must be unique across the entire request, not only within its own section. Conditions reference questions by this number, so two questions that share a number will make conditional logic target the wrong field. Number them in order from 1 and it stays simple.

The payload is strictly validated. The call fails if a required key is missing, or if a property name is unknown or misspelled. Write data_type, not data-type.

Field types

Each question's data_type is one of the exact values below, and it sets the kind of field the client fills in.

Text

Value Field
single-line Single-line text box
text Text box
multi-line text Multi-line text area
formatted text Rich text editor

Contact

Value Field
email Email address, validated
phone Phone number
url Web address, validated
address Structured address
country select Country picker

File uploads

Value Field
single image upload One image
multiple image upload Several images
single file upload One file
multiple file upload Several files

Numbers and dates

Value Field
number Number
currency Money amount
date/time Date and time picker
date range Start and end dates

Ratings

Value Field
numeric rating Rating on a numeric scale
star rating Star rating

Choices

Value Field
single select option Radio buttons, one choice
multi select options Checkboxes, several choices
dropdown Dropdown, one choice
task list Checklist

Table

Value Field
table Columns you set, with the client adding rows

Other

Value Field
signature Signature
button Button
icon Icon
color picker Color picker

Copy each value exactly. Anything not on this list, including a typo, fails validation instead of falling back to a default field.

The four choice types need an options array of their choices, and table needs a columns array of its headings. If you leave those out the field is still created, only with nothing in it.

Conditional visibility with show_when

Add a show_when object to any question to keep it hidden until the client's earlier answers meet your conditions.

show_when takes two keys:

  • conditions: an array of condition objects, each with a question_number to watch, a condition operator, and a value to compare against.
  • logical_operator: "and" to require every condition, or "or" to require any one.

Include logical_operator in every show_when, even when there is a single condition. Leave it out and the request fails validation.

condition is one of:

Operator Matches when
contains The answer contains your text
equals The answer is exactly your value
does not equal The answer is anything but your value
less than The answer is a smaller number
greater than The answer is a larger number
is empty The client has not answered
has a value The client has answered

For a choice field (a dropdown, a single or multi select, or a task list), an equals or does not equal test only works when value is the exact text of one of that question's options. If it matches none of them, the whole condition is thrown away.

Keep a conditional question on the same page as every question it depends on. Conditional logic is built per page, so a show_when that points at a question_number on another page is ignored, and the field shows to the client regardless.

Draft and published requests

New requests are created as drafts unless you set status to published, and those are the only two values the endpoint takes. A draft stays in your account and does not reach the client until you publish it.

Publishing on creation needs a verified account, so confirm the account first. A published request also counts toward your plan's active request limit, so the call fails if you are already at the limit. A draft does not count toward the limit, so you can use drafts to prepare work before you publish.

Creating or matching a client

You name the client with client_email. If a client with that email already exists, the request is attached to them. If not, the endpoint creates a new client from client_email and client_full_name. In that case, client_full_name is required and the token needs the write_clients scope.

The response says whether that client was created, updated, or matched to an existing one. You cannot point a request at one of your own team members, so the call fails if the email belongs to a team member.

Rate limits

Each access token gets 20 write calls every 10 seconds, and 50 reads. Creating a request counts as a write. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Going over the limit returns 429 with a Retry-After header that tells you how long to wait.

Full example

This creates a two-page vendor onboarding form with a mix of field types and questions that appear based on earlier answers.

{
  "name": "Vendor Application Form",
  "client_email": "vendor@example.com",
  "client_full_name": "Jane Smith",
  "company_name": "Smith Supplies",
  "due": "2026-04-15",
  "status": "published",
  "pages_data": [
    {
      "name": "Company Information",
      "sections_data": [
        {
          "name": "Basic Details",
          "questions_data": [
            {
              "question": "Legal business name",
              "data_type": "single-line",
              "question_number": 1
            },
            {
              "question": "Business type",
              "data_type": "dropdown",
              "question_number": 2,
              "options": ["Sole Proprietor", "Partnership", "Corporation", "LLC", "Other"]
            },
            {
              "question": "If Other, please specify",
              "data_type": "single-line",
              "question_number": 3,
              "show_when": {
                "conditions": [
                  { "question_number": 2, "condition": "equals", "value": "Other" }
                ],
                "logical_operator": "and"
              }
            },
            {
              "question": "Business address",
              "data_type": "address",
              "question_number": 4
            },
            {
              "question": "Company website",
              "data_type": "url",
              "question_number": 5
            }
          ]
        },
        {
          "name": "Company Profile",
          "questions_data": [
            {
              "question": "Company logo",
              "data_type": "single image upload",
              "question_number": 6,
              "instructions": "Please upload a high-resolution PNG or SVG file"
            },
            {
              "question": "Describe your products or services",
              "data_type": "multi-line text",
              "question_number": 7
            }
          ]
        }
      ]
    },
    {
      "name": "Compliance & Documents",
      "sections_data": [
        {
          "name": "Certifications",
          "questions_data": [
            {
              "question": "Do you hold any industry certifications?",
              "data_type": "single select option",
              "question_number": 8,
              "options": ["Yes", "No"]
            },
            {
              "question": "Upload certification documents",
              "data_type": "multiple file upload",
              "question_number": 9,
              "instructions": "PDF or scanned copies accepted",
              "show_when": {
                "conditions": [
                  { "question_number": 8, "condition": "equals", "value": "Yes" }
                ],
                "logical_operator": "and"
              }
            },
            {
              "question": "List certifications and expiry dates",
              "data_type": "table",
              "question_number": 10,
              "columns": ["Certification Name", "Issuing Body", "Expiry Date"],
              "show_when": {
                "conditions": [
                  { "question_number": 8, "condition": "equals", "value": "Yes" }
                ],
                "logical_operator": "and"
              }
            }
          ]
        },
        {
          "name": "Agreement",
          "questions_data": [
            {
              "question": "Compliance checklist",
              "data_type": "task list",
              "question_number": 11,
              "options": [
                "I agree to the Terms of Service",
                "I have read the Privacy Policy",
                "I confirm all information is accurate"
              ]
            },
            {
              "question": "Authorized signature",
              "data_type": "signature",
              "question_number": 12
            }
          ]
        }
      ]
    }
  ]
}