Skip to content
POST
/v1/project/signup-forms
curl --request POST \
--url https://api.proxymail.qa/v1/project/signup-forms \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "spec": { "version": 1, "name": "example", "site": "example", "language": "example", "country": "example", "screens": [ { "title": "example", "path": "example", "screen_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "fields": [ { "section": "example", "custom_field": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "required": true, "label": "example", "testid": "example", "options": { "type": "text", "country": "example", "min_length": 1, "max_length": 1, "classes": [ "lower" ], "min_age": 1, "choices": [ "example" ] } } ] } ] }, "choices": { "additionalProperty": "yours" }, "tidy": { "remove": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "move": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "testid": "example" } ] } }'

Saves a sign-up form’s spec: a new form, the one with this id, or the one with the same name. Missing labels and test ids are filled in. A field with section custom names one of the project’s own custom fields (custom_field, with a label and options.type): the form describes it for code and tests, and that custom field fills it. For the fields the built-in fill doesn’t cover (team size, the terms box, a phone, an ID or tax number and the other choices), saving uses a custom field that already fills the field and makes a ready-made one, matched by the field’s test id, only where nothing does (only a lead’s key makes the ID and tax number ones); fields_filled_by says what fills each. clashes: the project’s own custom field also fills a field but the form’s wins; save again with choices once the person says. leftovers: custom fields the form made and no longer uses; save again with tidy to move or remove them. Nothing is removed without tidy. On a locked project, a key whose creator isn’t a lead asks the leads instead: 202 with status: "requested", one request for the whole form, which waits as a draft until a lead approves it in Project settings. A project has up to 20 forms.

Media typeapplication/json
object
id

The form to change. Leave out to add one, or to change the one with the same name.

string format: uuid
<= 36 characters
spec
required

The form. Only name and screens are required.

object
version
integer
Allowed values: 1
name
required

What the form is called, such as Main sign-up.

string
<= 80 characters
site

The site it’s on, as the project lists it, such as https://staging.example.com/*. Leave out to match on every site.

string
<= 300 characters
language

The form’s language, for its default labels: en (the default), de, fr, es, it, pt, nl, zh or ja.

string
country

A two-letter country code for the fields that depend on one (IDs, VAT numbers, phones, addresses).

string
screens
required

The screens in order, up to 10, with up to 60 fields in all.

Array<object>
>= 1 items <= 10 items
object
title

The screen’s heading.

string
<= 80 characters
path

The page’s path, such as /signup.

string
screen_id

A sign-up screen the project keeps, from list_sites.

string format: uuid
fields
required

The fields in order. Each section once in the form.

Array<object>
>= 1 items <= 30 items
object
section
required

A section id from list_form_sections, such as email, password or business.team_size; or custom, with custom_field, for a question one of the project’s own custom fields answers.

string
custom_field

Section custom only: the custom field that fills it, by its id from list_custom_fields. It keeps deciding the value; the form puts the field in its code, tests and preview. Give the field the test id or label that custom field looks for.

string format: uuid
required

Defaults to true.

boolean
label

The field’s label; defaults to the section’s label in the form’s language. Needed for section custom.

string
<= 80 characters
testid

Its data-testid; defaults to signup- and the section id with dashes, such as signup-business-team-size, or for section custom signup- and the label, such as signup-team-size.

string
<= 100 characters
options

Only what the section takes.

object
type

Section custom only: a text box, a drop-down (with choices) or a tick box. Defaults to select with choices, else text.

string
Allowed values: text select checkbox
country

A two-letter country code, for a country-dependent section.

string
min_length

Password only.

integer
max_length

Password only.

integer
classes

Password only: the kinds of character it must have.

Array<string>
Allowed values: lower upper digit symbol
min_age

Date of birth only: the youngest age the form accepts.

integer
choices

The options of a drop-down or radio group (gender, language, how someone heard, role, team size, or a section custom drop-down).

Array<string>
choices

Your answer to clashes a save reported, by the field’s test id: “yours” keeps the project’s own custom field (then remove the form’s with tidy), “form” keeps the form’s ready-made field over it. Ask the person first.

object
key
additional properties
string
Allowed values: yours form
tidy

What to do with the leftovers a save reported, once the person says: remove takes custom field ids; move takes { id, testid } to point a renamed field’s custom field at its new test id. Leftovers left out stay as custom fields, no longer the form’s. Without tidy, nothing is removed and they’re reported again.

object
remove
Array<string>
<= 30 items
move
Array<object>
<= 30 items
object
id
required
string format: uuid
<= 36 characters
testid
required
string

Changed

Media typeapplication/json
object
status

Requested: the project is locked, so a lead was asked.

string
Allowed values: saved removed requested
form
object
id
string format: uuid
name
string
status

Requested: a lead hasn’t answered yet; draft: asked for and never approved.

string
Allowed values: saved requested draft
site
string | null
screens
integer
fields
integer
created_via
string
Allowed values: app extension agent api
agent_name
string | null
created_at
string format: date-time
updated_at
string format: date-time
spec

The form. Only name and screens are required.

object
version
integer
Allowed values: 1
name
required

What the form is called, such as Main sign-up.

string
<= 80 characters
site

The site it’s on, as the project lists it, such as https://staging.example.com/*. Leave out to match on every site.

string
<= 300 characters
language

The form’s language, for its default labels: en (the default), de, fr, es, it, pt, nl, zh or ja.

string
country

A two-letter country code for the fields that depend on one (IDs, VAT numbers, phones, addresses).

string
screens
required

The screens in order, up to 10, with up to 60 fields in all.

Array<object>
>= 1 items <= 10 items
object
title

The screen’s heading.

string
<= 80 characters
path

The page’s path, such as /signup.

string
screen_id

A sign-up screen the project keeps, from list_sites.

string format: uuid
fields
required

The fields in order. Each section once in the form.

Array<object>
>= 1 items <= 30 items
object
section
required

A section id from list_form_sections, such as email, password or business.team_size; or custom, with custom_field, for a question one of the project’s own custom fields answers.

string
custom_field

Section custom only: the custom field that fills it, by its id from list_custom_fields. It keeps deciding the value; the form puts the field in its code, tests and preview. Give the field the test id or label that custom field looks for.

string format: uuid
required

Defaults to true.

boolean
label

The field’s label; defaults to the section’s label in the form’s language. Needed for section custom.

string
<= 80 characters
testid

Its data-testid; defaults to signup- and the section id with dashes, such as signup-business-team-size, or for section custom signup- and the label, such as signup-team-size.

string
<= 100 characters
options

Only what the section takes.

object
type

Section custom only: a text box, a drop-down (with choices) or a tick box. Defaults to select with choices, else text.

string
Allowed values: text select checkbox
country

A two-letter country code, for a country-dependent section.

string
min_length

Password only.

integer
max_length

Password only.

integer
classes

Password only: the kinds of character it must have.

Array<string>
Allowed values: lower upper digit symbol
min_age

Date of birth only: the youngest age the form accepts.

integer
choices

The options of a drop-down or radio group (gender, language, how someone heard, role, team size, or a section custom drop-down).

Array<string>
custom_fields

The custom fields the form needs.

Array<object>
object
id

The custom field to change.

string format: uuid
<= 36 characters
enabled

Ignored here, and allowed so a custom field can be sent back as listed. PATCH this path to turn one on or off.

boolean
name
required
string
<= 80 characters
match
required

How to recognise the field: words its label or name contains (3 to 100 characters, or 2 in Chinese, Japanese or Korean), with up to 9 more phrases in also, such as its label in other languages; or its exact test ID, name or id attribute; or, for a ready-made custom field, kind with its section as text. Saving replaces the custom field, so send every phrase to keep.

object
on
required
string
Allowed values: words test_id name html_id kind
text
required
string
<= 100 characters
also

Words only: more phrases that recognise the same field, such as its label in the site’s other languages.

Array<string>
<= 9 items
site

Its host or a site pattern, such as staging.acme.dev or https://.acme.dev/, or null for every site. It needn’t be one of the project’s sites yet; a blocked site is refused.

string | null
<= 300 characters
path

A page path such as /signup. It covers /signup, /signup/business and the same page under a language, such as /de/signup. Leave it out, or send null, for every page of the site.

string | null
<= 200 characters
field_type
string | null
Allowed values: text textarea number select checkbox radio
value
required

What goes in the field. text: { text }. template: { template } with {first_name}, {last_name}, {full_name}, {username}, {email}, {company}, {country} or {digits:N} (N from 1 to 12). option: { option }, the option to pick. list: { items }, 2 to 20, one picked for each account. options: { options }, 1 to 20, every one for every account: ticks the boxes of a group (matched by their shared name or words in the question they answer) or selects them in a drop-down that takes several answers, and boxes not listed are unticked, though a consent box, a marketing box or a box with its own custom field is left as it is. Never a radio group. checkbox: { checked }. generate: Proxy Mail QA makes up a value that suits the field (the same for the same account), on any field but a checkbox, never a personal ID field. leave: leave the field as it is. ready_made: { section }, matched on kind (or test_id when a sign-up form made it), Proxy Mail QA’s own safe value, where it has one: phone (a number set aside for fiction, or phones: the team’s own test number per country), id.national, id.tax, id.passport, business.vat and business.tax (a fake value only where one can never be a real person’s, or ids_from: a KYC vendor’s sandbox values), gender, referral_source, language, business.role, business.team_size and business.type (one of the field’s options) and consent.terms (ticked unless checked is false).

object
kind
required
string
Allowed values: text template option list options checkbox generate leave ready_made
text
string
<= 200 characters
template
string
<= 200 characters
option
string
<= 100 characters
items
Array<string>
>= 2 items <= 20 items
options
Array<string>
>= 1 items <= 20 items
checked

Checkbox, or ready_made consent.terms (true by default).

boolean
section

Ready_made only: the field catalogue section it fills.

string
Allowed values: phone id.national id.tax id.passport business.vat business.tax gender referral_source language business.role business.team_size business.type consent.terms
ids_from

Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.

string
Allowed values: safe stripe plaid onfido veriff didit cashfree setu
phones

Ready_made phone only: the team’s own test numbers, one per country, for accounts in countries with no numbers set aside for fiction. Never a real person’s number.

Array<object>
<= 20 items
object
country
required
string
/^[A-Za-z]{2}$/
number
required

4 to 30 digits, spaces, brackets or dashes, with an optional leading +.

string
<= 30 characters
tag_answer

An option or one of a list only: tag the account with the answer.

boolean
fills

How each field gets its value.

Array<object>
object
testid
string
section
string
fill
string
Allowed values: built_in custom_field never
requested

What a member asked the leads for, while a request waits.

object
name
string
spec

The form. Only name and screens are required.

object
version
integer
Allowed values: 1
name
required

What the form is called, such as Main sign-up.

string
<= 80 characters
site

The site it’s on, as the project lists it, such as https://staging.example.com/*. Leave out to match on every site.

string
<= 300 characters
language

The form’s language, for its default labels: en (the default), de, fr, es, it, pt, nl, zh or ja.

string
country

A two-letter country code for the fields that depend on one (IDs, VAT numbers, phones, addresses).

string
screens
required

The screens in order, up to 10, with up to 60 fields in all.

Array<object>
>= 1 items <= 10 items
object
title

The screen’s heading.

string
<= 80 characters
path

The page’s path, such as /signup.

string
screen_id

A sign-up screen the project keeps, from list_sites.

string format: uuid
fields
required

The fields in order. Each section once in the form.

Array<object>
>= 1 items <= 30 items
object
section
required

A section id from list_form_sections, such as email, password or business.team_size; or custom, with custom_field, for a question one of the project’s own custom fields answers.

string
custom_field

Section custom only: the custom field that fills it, by its id from list_custom_fields. It keeps deciding the value; the form puts the field in its code, tests and preview. Give the field the test id or label that custom field looks for.

string format: uuid
required

Defaults to true.

boolean
label

The field’s label; defaults to the section’s label in the form’s language. Needed for section custom.

string
<= 80 characters
testid

Its data-testid; defaults to signup- and the section id with dashes, such as signup-business-team-size, or for section custom signup- and the label, such as signup-team-size.

string
<= 100 characters
options

Only what the section takes.

object
type

Section custom only: a text box, a drop-down (with choices) or a tick box. Defaults to select with choices, else text.

string
Allowed values: text select checkbox
country

A two-letter country code, for a country-dependent section.

string
min_length

Password only.

integer
max_length

Password only.

integer
classes

Password only: the kinds of character it must have.

Array<string>
Allowed values: lower upper digit symbol
min_age

Date of birth only: the youngest age the form accepts.

integer
choices

The options of a drop-down or radio group (gender, language, how someone heard, role, team size, or a section custom drop-down).

Array<string>
custom_fields
Array<object>
object
id

The custom field to change.

string format: uuid
<= 36 characters
enabled

Ignored here, and allowed so a custom field can be sent back as listed. PATCH this path to turn one on or off.

boolean
name
required
string
<= 80 characters
match
required

How to recognise the field: words its label or name contains (3 to 100 characters, or 2 in Chinese, Japanese or Korean), with up to 9 more phrases in also, such as its label in other languages; or its exact test ID, name or id attribute; or, for a ready-made custom field, kind with its section as text. Saving replaces the custom field, so send every phrase to keep.

object
on
required
string
Allowed values: words test_id name html_id kind
text
required
string
<= 100 characters
also

Words only: more phrases that recognise the same field, such as its label in the site’s other languages.

Array<string>
<= 9 items
site

Its host or a site pattern, such as staging.acme.dev or https://.acme.dev/, or null for every site. It needn’t be one of the project’s sites yet; a blocked site is refused.

string | null
<= 300 characters
path

A page path such as /signup. It covers /signup, /signup/business and the same page under a language, such as /de/signup. Leave it out, or send null, for every page of the site.

string | null
<= 200 characters
field_type
string | null
Allowed values: text textarea number select checkbox radio
value
required

What goes in the field. text: { text }. template: { template } with {first_name}, {last_name}, {full_name}, {username}, {email}, {company}, {country} or {digits:N} (N from 1 to 12). option: { option }, the option to pick. list: { items }, 2 to 20, one picked for each account. options: { options }, 1 to 20, every one for every account: ticks the boxes of a group (matched by their shared name or words in the question they answer) or selects them in a drop-down that takes several answers, and boxes not listed are unticked, though a consent box, a marketing box or a box with its own custom field is left as it is. Never a radio group. checkbox: { checked }. generate: Proxy Mail QA makes up a value that suits the field (the same for the same account), on any field but a checkbox, never a personal ID field. leave: leave the field as it is. ready_made: { section }, matched on kind (or test_id when a sign-up form made it), Proxy Mail QA’s own safe value, where it has one: phone (a number set aside for fiction, or phones: the team’s own test number per country), id.national, id.tax, id.passport, business.vat and business.tax (a fake value only where one can never be a real person’s, or ids_from: a KYC vendor’s sandbox values), gender, referral_source, language, business.role, business.team_size and business.type (one of the field’s options) and consent.terms (ticked unless checked is false).

object
kind
required
string
Allowed values: text template option list options checkbox generate leave ready_made
text
string
<= 200 characters
template
string
<= 200 characters
option
string
<= 100 characters
items
Array<string>
>= 2 items <= 20 items
options
Array<string>
>= 1 items <= 20 items
checked

Checkbox, or ready_made consent.terms (true by default).

boolean
section

Ready_made only: the field catalogue section it fills.

string
Allowed values: phone id.national id.tax id.passport business.vat business.tax gender referral_source language business.role business.team_size business.type consent.terms
ids_from

Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.

string
Allowed values: safe stripe plaid onfido veriff didit cashfree setu
phones

Ready_made phone only: the team’s own test numbers, one per country, for accounts in countries with no numbers set aside for fiction. Never a real person’s number.

Array<object>
<= 20 items
object
country
required
string
/^[A-Za-z]{2}$/
number
required

4 to 30 digits, spaces, brackets or dashes, with an optional leading +.

string
<= 30 characters
tag_answer

An option or one of a list only: tag the account with the answer.

boolean
request

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

object
id
required
string format: uuid
kind
required
string
Allowed values: save_custom_field delete_custom_field add_site remove_site set_guesses set_multi_step save_signup_screen remove_signup_screen set_custom_field_enabled set_standard_field save_signup_form
target_id
required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid
summary
required

The custom field’s name, the site, the screen, or the setting’s new choice.

string
change
required

What it changes, as it applies once a lead approves it.

object
note
required

What the person who asked wrote for the leads.

string | null
status
required
string
Allowed values: requested approved declined withdrawn expired unlocked
reason
required

A lead’s reason for declining.

string | null
fields_filled_by

Saving: what fills each field a custom field fills. made: the save makes a ready-made one; form: a ready-made field a form made; yours: the project’s own. A field with section custom has named: true and finds: whether its custom field finds it on the page.

Array<object>
object
key
additional properties
any
clashes

Saving: fields the project’s own custom field also fills, where the form’s ready-made field wins.

Array<object>
object
key
additional properties
any
leftovers

Saving: custom fields the form made and no longer uses (gone, renamed or yours).

Array<object>
object
key
additional properties
any
tidied

Saving with tidy: the custom fields moved, removed, asked about and kept, by name.

object
key
additional properties
any
id

The form removed.

string format: uuid
custom_fields_removed

Removing: the custom fields that went with it, by name.

Array<string>
custom_fields_asked

Removing with remove_custom_fields on a locked project, for a key whose creator isn’t a lead: those the leads were asked to remove.

Array<string>
custom_fields_kept

Removing with remove_custom_fields: those that stay, as someone else made them on an unlocked project, or a request to the leads couldn’t be sent (5 waiting, or a different request about it waiting).

Array<string>
request

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

object
id
required
string format: uuid
kind
required
string
Allowed values: save_custom_field delete_custom_field add_site remove_site set_guesses set_multi_step save_signup_screen remove_signup_screen set_custom_field_enabled set_standard_field save_signup_form
target_id
required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid
summary
required

The custom field’s name, the site, the screen, or the setting’s new choice.

string
change
required

What it changes, as it applies once a lead approves it.

object
note
required

What the person who asked wrote for the leads.

string | null
status
required
string
Allowed values: requested approved declined withdrawn expired unlocked
reason
required

A lead’s reason for declining.

string | null

Example

{
"status": "saved",
"form": {
"status": "saved",
"created_via": "app",
"spec": {
"version": 1,
"screens": [
{
"fields": [
{
"options": {
"type": "text",
"classes": [
"lower"
]
}
}
]
}
]
},
"custom_fields": [
{
"name": "Company size",
"match": {
"on": "words"
},
"site": "https://staging.acme.dev/*",
"path": "/signup",
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
}
],
"fills": [
{
"fill": "built_in"
}
],
"requested": {
"spec": {
"version": 1,
"screens": [
{
"fields": [
{
"options": {
"type": "text",
"classes": [
"lower"
]
}
}
]
}
]
},
"custom_fields": [
{
"name": "Company size",
"match": {
"on": "words"
},
"site": "https://staging.acme.dev/*",
"path": "/signup",
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
}
]
},
"request": {
"kind": "save_custom_field",
"status": "requested"
}
},
"request": {
"kind": "save_custom_field",
"status": "requested"
}
}

Added

Media typeapplication/json
object
status

Requested: the project is locked, so a lead was asked.

string
Allowed values: saved removed requested
form
object
id
string format: uuid
name
string
status

Requested: a lead hasn’t answered yet; draft: asked for and never approved.

string
Allowed values: saved requested draft
site
string | null
screens
integer
fields
integer
created_via
string
Allowed values: app extension agent api
agent_name
string | null
created_at
string format: date-time
updated_at
string format: date-time
spec

The form. Only name and screens are required.

object
version
integer
Allowed values: 1
name
required

What the form is called, such as Main sign-up.

string
<= 80 characters
site

The site it’s on, as the project lists it, such as https://staging.example.com/*. Leave out to match on every site.

string
<= 300 characters
language

The form’s language, for its default labels: en (the default), de, fr, es, it, pt, nl, zh or ja.

string
country

A two-letter country code for the fields that depend on one (IDs, VAT numbers, phones, addresses).

string
screens
required

The screens in order, up to 10, with up to 60 fields in all.

Array<object>
>= 1 items <= 10 items
object
title

The screen’s heading.

string
<= 80 characters
path

The page’s path, such as /signup.

string
screen_id

A sign-up screen the project keeps, from list_sites.

string format: uuid
fields
required

The fields in order. Each section once in the form.

Array<object>
>= 1 items <= 30 items
object
section
required

A section id from list_form_sections, such as email, password or business.team_size; or custom, with custom_field, for a question one of the project’s own custom fields answers.

string
custom_field

Section custom only: the custom field that fills it, by its id from list_custom_fields. It keeps deciding the value; the form puts the field in its code, tests and preview. Give the field the test id or label that custom field looks for.

string format: uuid
required

Defaults to true.

boolean
label

The field’s label; defaults to the section’s label in the form’s language. Needed for section custom.

string
<= 80 characters
testid

Its data-testid; defaults to signup- and the section id with dashes, such as signup-business-team-size, or for section custom signup- and the label, such as signup-team-size.

string
<= 100 characters
options

Only what the section takes.

object
type

Section custom only: a text box, a drop-down (with choices) or a tick box. Defaults to select with choices, else text.

string
Allowed values: text select checkbox
country

A two-letter country code, for a country-dependent section.

string
min_length

Password only.

integer
max_length

Password only.

integer
classes

Password only: the kinds of character it must have.

Array<string>
Allowed values: lower upper digit symbol
min_age

Date of birth only: the youngest age the form accepts.

integer
choices

The options of a drop-down or radio group (gender, language, how someone heard, role, team size, or a section custom drop-down).

Array<string>
custom_fields

The custom fields the form needs.

Array<object>
object
id

The custom field to change.

string format: uuid
<= 36 characters
enabled

Ignored here, and allowed so a custom field can be sent back as listed. PATCH this path to turn one on or off.

boolean
name
required
string
<= 80 characters
match
required

How to recognise the field: words its label or name contains (3 to 100 characters, or 2 in Chinese, Japanese or Korean), with up to 9 more phrases in also, such as its label in other languages; or its exact test ID, name or id attribute; or, for a ready-made custom field, kind with its section as text. Saving replaces the custom field, so send every phrase to keep.

object
on
required
string
Allowed values: words test_id name html_id kind
text
required
string
<= 100 characters
also

Words only: more phrases that recognise the same field, such as its label in the site’s other languages.

Array<string>
<= 9 items
site

Its host or a site pattern, such as staging.acme.dev or https://.acme.dev/, or null for every site. It needn’t be one of the project’s sites yet; a blocked site is refused.

string | null
<= 300 characters
path

A page path such as /signup. It covers /signup, /signup/business and the same page under a language, such as /de/signup. Leave it out, or send null, for every page of the site.

string | null
<= 200 characters
field_type
string | null
Allowed values: text textarea number select checkbox radio
value
required

What goes in the field. text: { text }. template: { template } with {first_name}, {last_name}, {full_name}, {username}, {email}, {company}, {country} or {digits:N} (N from 1 to 12). option: { option }, the option to pick. list: { items }, 2 to 20, one picked for each account. options: { options }, 1 to 20, every one for every account: ticks the boxes of a group (matched by their shared name or words in the question they answer) or selects them in a drop-down that takes several answers, and boxes not listed are unticked, though a consent box, a marketing box or a box with its own custom field is left as it is. Never a radio group. checkbox: { checked }. generate: Proxy Mail QA makes up a value that suits the field (the same for the same account), on any field but a checkbox, never a personal ID field. leave: leave the field as it is. ready_made: { section }, matched on kind (or test_id when a sign-up form made it), Proxy Mail QA’s own safe value, where it has one: phone (a number set aside for fiction, or phones: the team’s own test number per country), id.national, id.tax, id.passport, business.vat and business.tax (a fake value only where one can never be a real person’s, or ids_from: a KYC vendor’s sandbox values), gender, referral_source, language, business.role, business.team_size and business.type (one of the field’s options) and consent.terms (ticked unless checked is false).

object
kind
required
string
Allowed values: text template option list options checkbox generate leave ready_made
text
string
<= 200 characters
template
string
<= 200 characters
option
string
<= 100 characters
items
Array<string>
>= 2 items <= 20 items
options
Array<string>
>= 1 items <= 20 items
checked

Checkbox, or ready_made consent.terms (true by default).

boolean
section

Ready_made only: the field catalogue section it fills.

string
Allowed values: phone id.national id.tax id.passport business.vat business.tax gender referral_source language business.role business.team_size business.type consent.terms
ids_from

Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.

string
Allowed values: safe stripe plaid onfido veriff didit cashfree setu
phones

Ready_made phone only: the team’s own test numbers, one per country, for accounts in countries with no numbers set aside for fiction. Never a real person’s number.

Array<object>
<= 20 items
object
country
required
string
/^[A-Za-z]{2}$/
number
required

4 to 30 digits, spaces, brackets or dashes, with an optional leading +.

string
<= 30 characters
tag_answer

An option or one of a list only: tag the account with the answer.

boolean
fills

How each field gets its value.

Array<object>
object
testid
string
section
string
fill
string
Allowed values: built_in custom_field never
requested

What a member asked the leads for, while a request waits.

object
name
string
spec

The form. Only name and screens are required.

object
version
integer
Allowed values: 1
name
required

What the form is called, such as Main sign-up.

string
<= 80 characters
site

The site it’s on, as the project lists it, such as https://staging.example.com/*. Leave out to match on every site.

string
<= 300 characters
language

The form’s language, for its default labels: en (the default), de, fr, es, it, pt, nl, zh or ja.

string
country

A two-letter country code for the fields that depend on one (IDs, VAT numbers, phones, addresses).

string
screens
required

The screens in order, up to 10, with up to 60 fields in all.

Array<object>
>= 1 items <= 10 items
object
title

The screen’s heading.

string
<= 80 characters
path

The page’s path, such as /signup.

string
screen_id

A sign-up screen the project keeps, from list_sites.

string format: uuid
fields
required

The fields in order. Each section once in the form.

Array<object>
>= 1 items <= 30 items
object
section
required

A section id from list_form_sections, such as email, password or business.team_size; or custom, with custom_field, for a question one of the project’s own custom fields answers.

string
custom_field

Section custom only: the custom field that fills it, by its id from list_custom_fields. It keeps deciding the value; the form puts the field in its code, tests and preview. Give the field the test id or label that custom field looks for.

string format: uuid
required

Defaults to true.

boolean
label

The field’s label; defaults to the section’s label in the form’s language. Needed for section custom.

string
<= 80 characters
testid

Its data-testid; defaults to signup- and the section id with dashes, such as signup-business-team-size, or for section custom signup- and the label, such as signup-team-size.

string
<= 100 characters
options

Only what the section takes.

object
type

Section custom only: a text box, a drop-down (with choices) or a tick box. Defaults to select with choices, else text.

string
Allowed values: text select checkbox
country

A two-letter country code, for a country-dependent section.

string
min_length

Password only.

integer
max_length

Password only.

integer
classes

Password only: the kinds of character it must have.

Array<string>
Allowed values: lower upper digit symbol
min_age

Date of birth only: the youngest age the form accepts.

integer
choices

The options of a drop-down or radio group (gender, language, how someone heard, role, team size, or a section custom drop-down).

Array<string>
custom_fields
Array<object>
object
id

The custom field to change.

string format: uuid
<= 36 characters
enabled

Ignored here, and allowed so a custom field can be sent back as listed. PATCH this path to turn one on or off.

boolean
name
required
string
<= 80 characters
match
required

How to recognise the field: words its label or name contains (3 to 100 characters, or 2 in Chinese, Japanese or Korean), with up to 9 more phrases in also, such as its label in other languages; or its exact test ID, name or id attribute; or, for a ready-made custom field, kind with its section as text. Saving replaces the custom field, so send every phrase to keep.

object
on
required
string
Allowed values: words test_id name html_id kind
text
required
string
<= 100 characters
also

Words only: more phrases that recognise the same field, such as its label in the site’s other languages.

Array<string>
<= 9 items
site

Its host or a site pattern, such as staging.acme.dev or https://.acme.dev/, or null for every site. It needn’t be one of the project’s sites yet; a blocked site is refused.

string | null
<= 300 characters
path

A page path such as /signup. It covers /signup, /signup/business and the same page under a language, such as /de/signup. Leave it out, or send null, for every page of the site.

string | null
<= 200 characters
field_type
string | null
Allowed values: text textarea number select checkbox radio
value
required

What goes in the field. text: { text }. template: { template } with {first_name}, {last_name}, {full_name}, {username}, {email}, {company}, {country} or {digits:N} (N from 1 to 12). option: { option }, the option to pick. list: { items }, 2 to 20, one picked for each account. options: { options }, 1 to 20, every one for every account: ticks the boxes of a group (matched by their shared name or words in the question they answer) or selects them in a drop-down that takes several answers, and boxes not listed are unticked, though a consent box, a marketing box or a box with its own custom field is left as it is. Never a radio group. checkbox: { checked }. generate: Proxy Mail QA makes up a value that suits the field (the same for the same account), on any field but a checkbox, never a personal ID field. leave: leave the field as it is. ready_made: { section }, matched on kind (or test_id when a sign-up form made it), Proxy Mail QA’s own safe value, where it has one: phone (a number set aside for fiction, or phones: the team’s own test number per country), id.national, id.tax, id.passport, business.vat and business.tax (a fake value only where one can never be a real person’s, or ids_from: a KYC vendor’s sandbox values), gender, referral_source, language, business.role, business.team_size and business.type (one of the field’s options) and consent.terms (ticked unless checked is false).

object
kind
required
string
Allowed values: text template option list options checkbox generate leave ready_made
text
string
<= 200 characters
template
string
<= 200 characters
option
string
<= 100 characters
items
Array<string>
>= 2 items <= 20 items
options
Array<string>
>= 1 items <= 20 items
checked

Checkbox, or ready_made consent.terms (true by default).

boolean
section

Ready_made only: the field catalogue section it fills.

string
Allowed values: phone id.national id.tax id.passport business.vat business.tax gender referral_source language business.role business.team_size business.type consent.terms
ids_from

Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.

string
Allowed values: safe stripe plaid onfido veriff didit cashfree setu
phones

Ready_made phone only: the team’s own test numbers, one per country, for accounts in countries with no numbers set aside for fiction. Never a real person’s number.

Array<object>
<= 20 items
object
country
required
string
/^[A-Za-z]{2}$/
number
required

4 to 30 digits, spaces, brackets or dashes, with an optional leading +.

string
<= 30 characters
tag_answer

An option or one of a list only: tag the account with the answer.

boolean
request

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

object
id
required
string format: uuid
kind
required
string
Allowed values: save_custom_field delete_custom_field add_site remove_site set_guesses set_multi_step save_signup_screen remove_signup_screen set_custom_field_enabled set_standard_field save_signup_form
target_id
required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid
summary
required

The custom field’s name, the site, the screen, or the setting’s new choice.

string
change
required

What it changes, as it applies once a lead approves it.

object
note
required

What the person who asked wrote for the leads.

string | null
status
required
string
Allowed values: requested approved declined withdrawn expired unlocked
reason
required

A lead’s reason for declining.

string | null
fields_filled_by

Saving: what fills each field a custom field fills. made: the save makes a ready-made one; form: a ready-made field a form made; yours: the project’s own. A field with section custom has named: true and finds: whether its custom field finds it on the page.

Array<object>
object
key
additional properties
any
clashes

Saving: fields the project’s own custom field also fills, where the form’s ready-made field wins.

Array<object>
object
key
additional properties
any
leftovers

Saving: custom fields the form made and no longer uses (gone, renamed or yours).

Array<object>
object
key
additional properties
any
tidied

Saving with tidy: the custom fields moved, removed, asked about and kept, by name.

object
key
additional properties
any
id

The form removed.

string format: uuid
custom_fields_removed

Removing: the custom fields that went with it, by name.

Array<string>
custom_fields_asked

Removing with remove_custom_fields on a locked project, for a key whose creator isn’t a lead: those the leads were asked to remove.

Array<string>
custom_fields_kept

Removing with remove_custom_fields: those that stay, as someone else made them on an unlocked project, or a request to the leads couldn’t be sent (5 waiting, or a different request about it waiting).

Array<string>
request

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

object
id
required
string format: uuid
kind
required
string
Allowed values: save_custom_field delete_custom_field add_site remove_site set_guesses set_multi_step save_signup_screen remove_signup_screen set_custom_field_enabled set_standard_field save_signup_form
target_id
required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid
summary
required

The custom field’s name, the site, the screen, or the setting’s new choice.

string
change
required

What it changes, as it applies once a lead approves it.

object
note
required

What the person who asked wrote for the leads.

string | null
status
required
string
Allowed values: requested approved declined withdrawn expired unlocked
reason
required

A lead’s reason for declining.

string | null

Example

{
"status": "saved",
"form": {
"status": "saved",
"created_via": "app",
"spec": {
"version": 1,
"screens": [
{
"fields": [
{
"options": {
"type": "text",
"classes": [
"lower"
]
}
}
]
}
]
},
"custom_fields": [
{
"name": "Company size",
"match": {
"on": "words"
},
"site": "https://staging.acme.dev/*",
"path": "/signup",
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
}
],
"fills": [
{
"fill": "built_in"
}
],
"requested": {
"spec": {
"version": 1,
"screens": [
{
"fields": [
{
"options": {
"type": "text",
"classes": [
"lower"
]
}
}
]
}
]
},
"custom_fields": [
{
"name": "Company size",
"match": {
"on": "words"
},
"site": "https://staging.acme.dev/*",
"path": "/signup",
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
}
]
},
"request": {
"kind": "save_custom_field",
"status": "requested"
}
},
"request": {
"kind": "save_custom_field",
"status": "requested"
}
}

Asked a lead

Media typeapplication/json
object
status

Requested: the project is locked, so a lead was asked.

string
Allowed values: saved removed requested
form
object
id
string format: uuid
name
string
status

Requested: a lead hasn’t answered yet; draft: asked for and never approved.

string
Allowed values: saved requested draft
site
string | null
screens
integer
fields
integer
created_via
string
Allowed values: app extension agent api
agent_name
string | null
created_at
string format: date-time
updated_at
string format: date-time
spec

The form. Only name and screens are required.

object
version
integer
Allowed values: 1
name
required

What the form is called, such as Main sign-up.

string
<= 80 characters
site

The site it’s on, as the project lists it, such as https://staging.example.com/*. Leave out to match on every site.

string
<= 300 characters
language

The form’s language, for its default labels: en (the default), de, fr, es, it, pt, nl, zh or ja.

string
country

A two-letter country code for the fields that depend on one (IDs, VAT numbers, phones, addresses).

string
screens
required

The screens in order, up to 10, with up to 60 fields in all.

Array<object>
>= 1 items <= 10 items
object
title

The screen’s heading.

string
<= 80 characters
path

The page’s path, such as /signup.

string
screen_id

A sign-up screen the project keeps, from list_sites.

string format: uuid
fields
required

The fields in order. Each section once in the form.

Array<object>
>= 1 items <= 30 items
object
section
required

A section id from list_form_sections, such as email, password or business.team_size; or custom, with custom_field, for a question one of the project’s own custom fields answers.

string
custom_field

Section custom only: the custom field that fills it, by its id from list_custom_fields. It keeps deciding the value; the form puts the field in its code, tests and preview. Give the field the test id or label that custom field looks for.

string format: uuid
required

Defaults to true.

boolean
label

The field’s label; defaults to the section’s label in the form’s language. Needed for section custom.

string
<= 80 characters
testid

Its data-testid; defaults to signup- and the section id with dashes, such as signup-business-team-size, or for section custom signup- and the label, such as signup-team-size.

string
<= 100 characters
options

Only what the section takes.

object
type

Section custom only: a text box, a drop-down (with choices) or a tick box. Defaults to select with choices, else text.

string
Allowed values: text select checkbox
country

A two-letter country code, for a country-dependent section.

string
min_length

Password only.

integer
max_length

Password only.

integer
classes

Password only: the kinds of character it must have.

Array<string>
Allowed values: lower upper digit symbol
min_age

Date of birth only: the youngest age the form accepts.

integer
choices

The options of a drop-down or radio group (gender, language, how someone heard, role, team size, or a section custom drop-down).

Array<string>
custom_fields

The custom fields the form needs.

Array<object>
object
id

The custom field to change.

string format: uuid
<= 36 characters
enabled

Ignored here, and allowed so a custom field can be sent back as listed. PATCH this path to turn one on or off.

boolean
name
required
string
<= 80 characters
match
required

How to recognise the field: words its label or name contains (3 to 100 characters, or 2 in Chinese, Japanese or Korean), with up to 9 more phrases in also, such as its label in other languages; or its exact test ID, name or id attribute; or, for a ready-made custom field, kind with its section as text. Saving replaces the custom field, so send every phrase to keep.

object
on
required
string
Allowed values: words test_id name html_id kind
text
required
string
<= 100 characters
also

Words only: more phrases that recognise the same field, such as its label in the site’s other languages.

Array<string>
<= 9 items
site

Its host or a site pattern, such as staging.acme.dev or https://.acme.dev/, or null for every site. It needn’t be one of the project’s sites yet; a blocked site is refused.

string | null
<= 300 characters
path

A page path such as /signup. It covers /signup, /signup/business and the same page under a language, such as /de/signup. Leave it out, or send null, for every page of the site.

string | null
<= 200 characters
field_type
string | null
Allowed values: text textarea number select checkbox radio
value
required

What goes in the field. text: { text }. template: { template } with {first_name}, {last_name}, {full_name}, {username}, {email}, {company}, {country} or {digits:N} (N from 1 to 12). option: { option }, the option to pick. list: { items }, 2 to 20, one picked for each account. options: { options }, 1 to 20, every one for every account: ticks the boxes of a group (matched by their shared name or words in the question they answer) or selects them in a drop-down that takes several answers, and boxes not listed are unticked, though a consent box, a marketing box or a box with its own custom field is left as it is. Never a radio group. checkbox: { checked }. generate: Proxy Mail QA makes up a value that suits the field (the same for the same account), on any field but a checkbox, never a personal ID field. leave: leave the field as it is. ready_made: { section }, matched on kind (or test_id when a sign-up form made it), Proxy Mail QA’s own safe value, where it has one: phone (a number set aside for fiction, or phones: the team’s own test number per country), id.national, id.tax, id.passport, business.vat and business.tax (a fake value only where one can never be a real person’s, or ids_from: a KYC vendor’s sandbox values), gender, referral_source, language, business.role, business.team_size and business.type (one of the field’s options) and consent.terms (ticked unless checked is false).

object
kind
required
string
Allowed values: text template option list options checkbox generate leave ready_made
text
string
<= 200 characters
template
string
<= 200 characters
option
string
<= 100 characters
items
Array<string>
>= 2 items <= 20 items
options
Array<string>
>= 1 items <= 20 items
checked

Checkbox, or ready_made consent.terms (true by default).

boolean
section

Ready_made only: the field catalogue section it fills.

string
Allowed values: phone id.national id.tax id.passport business.vat business.tax gender referral_source language business.role business.team_size business.type consent.terms
ids_from

Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.

string
Allowed values: safe stripe plaid onfido veriff didit cashfree setu
phones

Ready_made phone only: the team’s own test numbers, one per country, for accounts in countries with no numbers set aside for fiction. Never a real person’s number.

Array<object>
<= 20 items
object
country
required
string
/^[A-Za-z]{2}$/
number
required

4 to 30 digits, spaces, brackets or dashes, with an optional leading +.

string
<= 30 characters
tag_answer

An option or one of a list only: tag the account with the answer.

boolean
fills

How each field gets its value.

Array<object>
object
testid
string
section
string
fill
string
Allowed values: built_in custom_field never
requested

What a member asked the leads for, while a request waits.

object
name
string
spec

The form. Only name and screens are required.

object
version
integer
Allowed values: 1
name
required

What the form is called, such as Main sign-up.

string
<= 80 characters
site

The site it’s on, as the project lists it, such as https://staging.example.com/*. Leave out to match on every site.

string
<= 300 characters
language

The form’s language, for its default labels: en (the default), de, fr, es, it, pt, nl, zh or ja.

string
country

A two-letter country code for the fields that depend on one (IDs, VAT numbers, phones, addresses).

string
screens
required

The screens in order, up to 10, with up to 60 fields in all.

Array<object>
>= 1 items <= 10 items
object
title

The screen’s heading.

string
<= 80 characters
path

The page’s path, such as /signup.

string
screen_id

A sign-up screen the project keeps, from list_sites.

string format: uuid
fields
required

The fields in order. Each section once in the form.

Array<object>
>= 1 items <= 30 items
object
section
required

A section id from list_form_sections, such as email, password or business.team_size; or custom, with custom_field, for a question one of the project’s own custom fields answers.

string
custom_field

Section custom only: the custom field that fills it, by its id from list_custom_fields. It keeps deciding the value; the form puts the field in its code, tests and preview. Give the field the test id or label that custom field looks for.

string format: uuid
required

Defaults to true.

boolean
label

The field’s label; defaults to the section’s label in the form’s language. Needed for section custom.

string
<= 80 characters
testid

Its data-testid; defaults to signup- and the section id with dashes, such as signup-business-team-size, or for section custom signup- and the label, such as signup-team-size.

string
<= 100 characters
options

Only what the section takes.

object
type

Section custom only: a text box, a drop-down (with choices) or a tick box. Defaults to select with choices, else text.

string
Allowed values: text select checkbox
country

A two-letter country code, for a country-dependent section.

string
min_length

Password only.

integer
max_length

Password only.

integer
classes

Password only: the kinds of character it must have.

Array<string>
Allowed values: lower upper digit symbol
min_age

Date of birth only: the youngest age the form accepts.

integer
choices

The options of a drop-down or radio group (gender, language, how someone heard, role, team size, or a section custom drop-down).

Array<string>
custom_fields
Array<object>
object
id

The custom field to change.

string format: uuid
<= 36 characters
enabled

Ignored here, and allowed so a custom field can be sent back as listed. PATCH this path to turn one on or off.

boolean
name
required
string
<= 80 characters
match
required

How to recognise the field: words its label or name contains (3 to 100 characters, or 2 in Chinese, Japanese or Korean), with up to 9 more phrases in also, such as its label in other languages; or its exact test ID, name or id attribute; or, for a ready-made custom field, kind with its section as text. Saving replaces the custom field, so send every phrase to keep.

object
on
required
string
Allowed values: words test_id name html_id kind
text
required
string
<= 100 characters
also

Words only: more phrases that recognise the same field, such as its label in the site’s other languages.

Array<string>
<= 9 items
site

Its host or a site pattern, such as staging.acme.dev or https://.acme.dev/, or null for every site. It needn’t be one of the project’s sites yet; a blocked site is refused.

string | null
<= 300 characters
path

A page path such as /signup. It covers /signup, /signup/business and the same page under a language, such as /de/signup. Leave it out, or send null, for every page of the site.

string | null
<= 200 characters
field_type
string | null
Allowed values: text textarea number select checkbox radio
value
required

What goes in the field. text: { text }. template: { template } with {first_name}, {last_name}, {full_name}, {username}, {email}, {company}, {country} or {digits:N} (N from 1 to 12). option: { option }, the option to pick. list: { items }, 2 to 20, one picked for each account. options: { options }, 1 to 20, every one for every account: ticks the boxes of a group (matched by their shared name or words in the question they answer) or selects them in a drop-down that takes several answers, and boxes not listed are unticked, though a consent box, a marketing box or a box with its own custom field is left as it is. Never a radio group. checkbox: { checked }. generate: Proxy Mail QA makes up a value that suits the field (the same for the same account), on any field but a checkbox, never a personal ID field. leave: leave the field as it is. ready_made: { section }, matched on kind (or test_id when a sign-up form made it), Proxy Mail QA’s own safe value, where it has one: phone (a number set aside for fiction, or phones: the team’s own test number per country), id.national, id.tax, id.passport, business.vat and business.tax (a fake value only where one can never be a real person’s, or ids_from: a KYC vendor’s sandbox values), gender, referral_source, language, business.role, business.team_size and business.type (one of the field’s options) and consent.terms (ticked unless checked is false).

object
kind
required
string
Allowed values: text template option list options checkbox generate leave ready_made
text
string
<= 200 characters
template
string
<= 200 characters
option
string
<= 100 characters
items
Array<string>
>= 2 items <= 20 items
options
Array<string>
>= 1 items <= 20 items
checked

Checkbox, or ready_made consent.terms (true by default).

boolean
section

Ready_made only: the field catalogue section it fills.

string
Allowed values: phone id.national id.tax id.passport business.vat business.tax gender referral_source language business.role business.team_size business.type consent.terms
ids_from

Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.

string
Allowed values: safe stripe plaid onfido veriff didit cashfree setu
phones

Ready_made phone only: the team’s own test numbers, one per country, for accounts in countries with no numbers set aside for fiction. Never a real person’s number.

Array<object>
<= 20 items
object
country
required
string
/^[A-Za-z]{2}$/
number
required

4 to 30 digits, spaces, brackets or dashes, with an optional leading +.

string
<= 30 characters
tag_answer

An option or one of a list only: tag the account with the answer.

boolean
request

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

object
id
required
string format: uuid
kind
required
string
Allowed values: save_custom_field delete_custom_field add_site remove_site set_guesses set_multi_step save_signup_screen remove_signup_screen set_custom_field_enabled set_standard_field save_signup_form
target_id
required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid
summary
required

The custom field’s name, the site, the screen, or the setting’s new choice.

string
change
required

What it changes, as it applies once a lead approves it.

object
note
required

What the person who asked wrote for the leads.

string | null
status
required
string
Allowed values: requested approved declined withdrawn expired unlocked
reason
required

A lead’s reason for declining.

string | null
fields_filled_by

Saving: what fills each field a custom field fills. made: the save makes a ready-made one; form: a ready-made field a form made; yours: the project’s own. A field with section custom has named: true and finds: whether its custom field finds it on the page.

Array<object>
object
key
additional properties
any
clashes

Saving: fields the project’s own custom field also fills, where the form’s ready-made field wins.

Array<object>
object
key
additional properties
any
leftovers

Saving: custom fields the form made and no longer uses (gone, renamed or yours).

Array<object>
object
key
additional properties
any
tidied

Saving with tidy: the custom fields moved, removed, asked about and kept, by name.

object
key
additional properties
any
id

The form removed.

string format: uuid
custom_fields_removed

Removing: the custom fields that went with it, by name.

Array<string>
custom_fields_asked

Removing with remove_custom_fields on a locked project, for a key whose creator isn’t a lead: those the leads were asked to remove.

Array<string>
custom_fields_kept

Removing with remove_custom_fields: those that stay, as someone else made them on an unlocked project, or a request to the leads couldn’t be sent (5 waiting, or a different request about it waiting).

Array<string>
request

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

object
id
required
string format: uuid
kind
required
string
Allowed values: save_custom_field delete_custom_field add_site remove_site set_guesses set_multi_step save_signup_screen remove_signup_screen set_custom_field_enabled set_standard_field save_signup_form
target_id
required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid
summary
required

The custom field’s name, the site, the screen, or the setting’s new choice.

string
change
required

What it changes, as it applies once a lead approves it.

object
note
required

What the person who asked wrote for the leads.

string | null
status
required
string
Allowed values: requested approved declined withdrawn expired unlocked
reason
required

A lead’s reason for declining.

string | null

Example

{
"status": "saved",
"form": {
"status": "saved",
"created_via": "app",
"spec": {
"version": 1,
"screens": [
{
"fields": [
{
"options": {
"type": "text",
"classes": [
"lower"
]
}
}
]
}
]
},
"custom_fields": [
{
"name": "Company size",
"match": {
"on": "words"
},
"site": "https://staging.acme.dev/*",
"path": "/signup",
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
}
],
"fills": [
{
"fill": "built_in"
}
],
"requested": {
"spec": {
"version": 1,
"screens": [
{
"fields": [
{
"options": {
"type": "text",
"classes": [
"lower"
]
}
}
]
}
]
},
"custom_fields": [
{
"name": "Company size",
"match": {
"on": "words"
},
"site": "https://staging.acme.dev/*",
"path": "/signup",
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
}
]
},
"request": {
"kind": "save_custom_field",
"status": "requested"
}
},
"request": {
"kind": "save_custom_field",
"status": "requested"
}
}

An error

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}

No API key, or one that isn’t valid: it may have been revoked, or its creator no longer has access to the project.

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}
WWW-Authenticate
string

Bearer realm="proxymail-qa", with error="invalid_token" when a key was sent but isn’t valid.

An error

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}

An error

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}

The path doesn’t take this method.

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}
Allow
string

The methods it takes, such as GET, PATCH.

An error

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}

The request body is over 64 KB, or 256 KB for POST /v1/form-values.

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}

Too many requests. With a Retry-After header, a per-minute limit was reached: the key’s requests (60 a minute on Free, 600 on Team), password reveals (30 a minute per person), or keys that aren’t valid from one network (120 a minute). Without one, error says which longer limit: daily_limit, the space’s new addresses for today (50 on Free), until midnight UTC; account_held, 10 addresses a day while a Free account’s recent use is looked at; or rate_limited when something is full, such as a project’s 50 custom fields.

Media typeapplication/json
object
error

What went wrong, as a code, such as bad_request (400), unauthorized (401), plan_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), content_too_large (413), rate_limited, daily_limit or account_held (429), or server_error (500).

string
message

What went wrong and what to do, in words.

string

Example generated

{
"error": "example",
"message": "example"
}
Retry-After
integer
>= 1

Seconds to wait before trying again. Sent with per-minute limits only.