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. |
Scroll sideways to see the whole table
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. |
Scroll sideways to see the whole table
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 |
Scroll sideways to see the whole table
Contact
| Value | Field |
|---|---|
email | Email address, validated |
phone | Phone number |
url | Web address, validated |
address | Structured address |
country select | Country picker |
Scroll sideways to see the whole table
File uploads
| Value | Field |
|---|---|
single image upload | One image |
multiple image upload | Several images |
single file upload | One file |
multiple file upload | Several files |
Scroll sideways to see the whole table
Numbers and dates
| Value | Field |
|---|---|
number | Number |
currency | Money amount |
date/time | Date and time picker |
date range | Start and end dates |
Scroll sideways to see the whole table
Ratings
| Value | Field |
|---|---|
numeric rating | Rating on a numeric scale |
star rating | Star rating |
Scroll sideways to see the whole table
Choices
| Value | Field |
|---|---|
single select option | Radio buttons, one choice |
multi select options | Checkboxes, several choices |
dropdown | Dropdown, one choice |
task list | Checklist |
Scroll sideways to see the whole table
Table
| Value | Field |
|---|---|
table | Columns you set, with the client adding rows |
Scroll sideways to see the whole table
Other
| Value | Field |
|---|---|
signature | Signature |
button | Button |
icon | Icon |
color picker | Color picker |
Scroll sideways to see the whole table
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 aquestion_numberto watch, aconditionoperator, and avalueto 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 |
Scroll sideways to see the whole table
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
}
]
}
]
}
]
}