Skip to content
POST
/v1/project/custom-fields
curl --request POST \
--url https://api.proxymail.qa/v1/project/custom-fields \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "enabled": true, "name": "Company size", "match": { "on": "words", "text": "example", "also": [ "example" ] }, "site": "https://staging.acme.dev/*", "path": "/signup", "field_type": "text", "value": { "kind": "text", "text": "example", "template": "example", "option": "example", "items": [ "example" ], "options": [ "example" ], "checked": true, "section": "phone", "ids_from": "safe", "phones": [ { "country": "IN", "number": "example" } ] }, "tag_answer": true }'

Adds a custom field, or changes the one with this id or with the same match, site and page. On a locked project, a key whose creator isn’t a lead asks the leads instead: the answer is 202 with status: "requested", and a lead approves or declines it in Project settings. A project has up to 50 custom fields, ready-made ones included. Payment fields can’t have one, and values that look like real secrets are refused. A ready-made custom field (value { kind: "ready_made", section }, match { on: "kind", text: section }) keeps its match and section once saved: change its name, site, page or options. Only a lead’s key adds or changes an ID or tax number one, or the Phone number’s phones: another key gets 403, or 202 on a locked project.

Media typeapplication/json
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

Example

Company size
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

Example

https://staging.acme.dev/*
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

Example

/signup
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}$/

Example

IN
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

Changed

Media typeapplication/json
object
status

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

string
Allowed values: saved removed requested
field

A custom field: what it recognises, where and what goes in it. Who made it, and when, are in the app.

object
id
required
string format: uuid
name
required
string
enabled
required

False when fills ignore it, as if it weren’t there. It still counts toward the 50.

boolean
match
required
object
on

Kind: a ready-made custom field, text its section.

string
Allowed values: words test_id name html_id kind
text
string
also

Words only, when it has more phrases.

Array<string>
site
required

The site pattern it applies on, or null for every site.

string | null
path
required

The page path it applies on, or null for every page.

string | null
field_type
required
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
required
boolean
id

The custom field removed.

string format: uuid
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",
"field": {
"match": {
"on": "words"
},
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
},
"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
field

A custom field: what it recognises, where and what goes in it. Who made it, and when, are in the app.

object
id
required
string format: uuid
name
required
string
enabled
required

False when fills ignore it, as if it weren’t there. It still counts toward the 50.

boolean
match
required
object
on

Kind: a ready-made custom field, text its section.

string
Allowed values: words test_id name html_id kind
text
string
also

Words only, when it has more phrases.

Array<string>
site
required

The site pattern it applies on, or null for every site.

string | null
path
required

The page path it applies on, or null for every page.

string | null
field_type
required
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
required
boolean
id

The custom field removed.

string format: uuid
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",
"field": {
"match": {
"on": "words"
},
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
},
"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
field

A custom field: what it recognises, where and what goes in it. Who made it, and when, are in the app.

object
id
required
string format: uuid
name
required
string
enabled
required

False when fills ignore it, as if it weren’t there. It still counts toward the 50.

boolean
match
required
object
on

Kind: a ready-made custom field, text its section.

string
Allowed values: words test_id name html_id kind
text
string
also

Words only, when it has more phrases.

Array<string>
site
required

The site pattern it applies on, or null for every site.

string | null
path
required

The page path it applies on, or null for every page.

string | null
field_type
required
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
required
boolean
id

The custom field removed.

string format: uuid
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",
"field": {
"match": {
"on": "words"
},
"field_type": "text",
"value": {
"kind": "text",
"section": "phone",
"ids_from": "safe",
"phones": [
{
"country": "IN"
}
]
}
},
"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"
}

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.