Add or change a custom field
const url = 'https://api.proxymail.qa/v1/project/custom-fields';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
The custom field to change.
Ignored here, and allowed so a custom field can be sent back as listed. PATCH this path to turn one on or off.
Example
Company sizeHow 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
Words only: more phrases that recognise the same field, such as its label in the site’s other languages.
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.
Example
https://staging.acme.dev/*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.
Example
/signupWhat 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
Checkbox, or ready_made consent.terms (true by default).
Ready_made only: the field catalogue section it fills.
Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.
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.
object
Example
IN4 to 30 digits, spaces, brackets or dashes, with an optional leading +.
An option or one of a list only: tag the account with the answer.
Responses
Section titled “Responses”Changed
object
Requested: the project is locked, so a lead was asked.
A custom field: what it recognises, where and what goes in it. Who made it, and when, are in the app.
object
False when fills ignore it, as if it weren’t there. It still counts toward the 50.
object
Kind: a ready-made custom field, text its section.
Words only, when it has more phrases.
The site pattern it applies on, or null for every site.
The page path it applies on, or null for every page.
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
Checkbox, or ready_made consent.terms (true by default).
Ready_made only: the field catalogue section it fills.
Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.
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.
object
4 to 30 digits, spaces, brackets or dashes, with an optional leading +.
The custom field removed.
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
The custom field, site, sign-up screen or sign-up form it changes, if any.
The custom field’s name, the site, the screen, or the setting’s new choice.
What it changes, as it applies once a lead approves it.
object
What the person who asked wrote for the leads.
A lead’s reason for declining.
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
object
Requested: the project is locked, so a lead was asked.
A custom field: what it recognises, where and what goes in it. Who made it, and when, are in the app.
object
False when fills ignore it, as if it weren’t there. It still counts toward the 50.
object
Kind: a ready-made custom field, text its section.
Words only, when it has more phrases.
The site pattern it applies on, or null for every site.
The page path it applies on, or null for every page.
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
Checkbox, or ready_made consent.terms (true by default).
Ready_made only: the field catalogue section it fills.
Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.
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.
object
4 to 30 digits, spaces, brackets or dashes, with an optional leading +.
The custom field removed.
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
The custom field, site, sign-up screen or sign-up form it changes, if any.
The custom field’s name, the site, the screen, or the setting’s new choice.
What it changes, as it applies once a lead approves it.
object
What the person who asked wrote for the leads.
A lead’s reason for declining.
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
object
Requested: the project is locked, so a lead was asked.
A custom field: what it recognises, where and what goes in it. Who made it, and when, are in the app.
object
False when fills ignore it, as if it weren’t there. It still counts toward the 50.
object
Kind: a ready-made custom field, text its section.
Words only, when it has more phrases.
The site pattern it applies on, or null for every site.
The page path it applies on, or null for every page.
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
Checkbox, or ready_made consent.terms (true by default).
Ready_made only: the field catalogue section it fills.
Ready_made ID and tax numbers only: safe (the default) or a KYC vendor’s sandbox values.
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.
object
4 to 30 digits, spaces, brackets or dashes, with an optional leading +.
The custom field removed.
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
The custom field, site, sign-up screen or sign-up form it changes, if any.
The custom field’s name, the site, the screen, or the setting’s new choice.
What it changes, as it applies once a lead approves it.
object
What the person who asked wrote for the leads.
A lead’s reason for declining.
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
object
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).
What went wrong and what to do, in words.
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.
object
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).
What went wrong and what to do, in words.
Example generated
{ "error": "example", "message": "example"}Headers
Section titled “Headers”Bearer realm="proxymail-qa", with error="invalid_token" when a key was sent but isn’t valid.
An error
object
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).
What went wrong and what to do, in words.
Example generated
{ "error": "example", "message": "example"}An error
object
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).
What went wrong and what to do, in words.
Example generated
{ "error": "example", "message": "example"}An error
object
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).
What went wrong and what to do, in words.
Example generated
{ "error": "example", "message": "example"}The request body is over 64 KB, or 256 KB for POST /v1/form-values.
object
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).
What went wrong and what to do, in words.
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.
object
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).
What went wrong and what to do, in words.
Example generated
{ "error": "example", "message": "example"}Headers
Section titled “Headers”Seconds to wait before trying again. Sent with per-minute limits only.