Skip to content
DELETE
/v1/project/signup-forms/{id}
curl --request DELETE \
--url 'https://api.proxymail.qa/v1/project/signup-forms/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0?remove_custom_fields=false' \
--header 'Authorization: Bearer <token>'

Removes it: whoever made it or a lead may. A request waiting for it is withdrawn. The custom fields it made stay, unless remove_custom_fields=true: then they go too, except any another form still uses. On a locked project only a lead removes them; otherwise whoever made one can. The answer names those removed and those kept.

id
required
string format: uuid
<= 36 characters
remove_custom_fields
boolean

Also remove the custom fields the form made.

Removed

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.

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.