---
title: "Custom fields: fill your app's own sign-up fields | Proxy Mail QA"
description: "Teach Proxy Mail QA your sign-up form's own fields, such as company size, so coding agents and Proxy Mail QA for Chrome fill them the same way."
url: https://proxymail.qa/docs/custom-fields
---

# Custom fields: fill your app's own sign-up fields

Sign-up forms ask more than an email and a password: company size, “How did you hear about us?”, a VAT number, a team-size drop-down, a terms box. A custom field says once, for everyone on the project, what goes in one of those fields. Your coding agent gets it from `form_values`, Proxy Mail QA for Chrome fills it with the rest of the form, and the same test account gets the same answers from both. Fields nobody has taught get a guess, marked so you can check it.

Proxy Mail QA only hands over values. Whether your form accepts them is what your test checks.

## Who uses them

- **Coding agents and test suites**, through `form_values` on the [MCP server](https://proxymail.qa/docs/mcp), the [REST API](https://proxymail.qa/docs/rest-api#custom-fields-and-guesses), the [npm package](https://proxymail.qa/docs/node#custom-fields-and-screens-after-the-first) and the [Python helper](https://proxymail.qa/docs/python#custom-fields-and-screens-after-the-first). A field a custom field decides comes back with `kind: "custom"`, and a guess with `kind: "guess"`.
- **People testing by hand**, with [Proxy Mail QA for Chrome](https://proxymail.qa/chrome-extension) 0.9.0 and later, which fills custom fields with the rest of the form and teaches new ones from the page.

Custom fields belong to the project, so one taught in the browser fills the same way for every agent and test suite on the project, and one an agent saves fills the same way in the browser.

## Teach one from the page

With Proxy Mail QA for Chrome 0.9.0 or later:

### Step 1: Fill the form

Fill the sign-up form as usual, from the button in its email field. The card lists what it filled, then **Guessed** and **Not filled**: the fields no custom field or built-in value covered.

### Step 2: Choose Teach

Choose **Teach** beside the field. The card asks “What goes in “Company size”?”, shows how it will recognise the field (its test ID, name or ID, or words from its label; **Change** shows the other ways) and where: the site and page you’re on, in every language. On a page in another language, **Save as** offers the custom fields that could be this field in another language. Choose one, such as “Referral code” in another language, to add this label to it instead of making a new one: its answer stays as it is, and **Add and fill** fills the field now.

### Step 3: Say what goes in

Pick one of the field’s options, type a text (with chips for the account’s first name, last name, username, company and random digits), give a list of answers, one for each account, or choose **Generate it** to have Proxy Mail QA make up a value that suits the field. **Leave it empty** keeps everything out of the field. The preview shows what this account gets.

### Step 4: Save and fill

**Save and fill** saves it for everyone on the project and fills the field now. A custom field taught from the page applies only on that site and page, in every language: **Use on every page** widens it to the whole site, and **Use on every site** to the whole project.

Teach isn’t offered on payment, password, CAPTCHA or upload fields. A field that already has a custom field shows **Change** instead, and its teach view adds **Remove**.

## Add one in Project settings

In the app, open the project switcher → **Project settings → Custom fields**. The card has two buttons: **Add ready-made field** for a phone number, an ID or tax number, a common choice or the terms box ([below](https://proxymail.qa/docs/custom-fields#ready-made-fields)), and **Add custom field** for your own:

- **Name**: what the field is, as people would say it (“Company size”). It’s shown on the account and in the extension’s card.
- **How to recognise it**: **Label or name contains**, **Test ID is**, **Name is** or **ID is**, and the text. For **Label or name contains**, put each phrase on its own line, such as the field’s label in each of your site’s languages, up to 10.
- **Where**: every site, or one of the project’s sites, with an optional page such as `/signup`.
- **What to put in**: **Text**, **From the test account**, **Generate it**, **Option**, **One of a list**, **Several options**, **Tick box** or **Leave it**, and for an option or a list, **Tag the account with the answer**. The preview shows the answer for the sample persona Jane Doe.

**Save custom field** adds it. Each row in the card shows how the custom field recognises its field, where it applies, its value, and who added it, when and from where (“from the extension”, “from Claude Code”). Edit and Delete are on the row, and one kept to a site has **Use on every site** in its menu. A custom field a [sign-up form](https://proxymail.qa/docs/signup-forms) made has a **From** tag with the form’s name, which opens the form.

A project’s sites are added in **Project settings → Sites** with **Add site**, or from Proxy Mail QA for Chrome, on the site itself. An agent or the API adds a site that doesn’t look live, such as a staging, dev or local one (`add_site`, `POST /v1/project/sites`); a site that looks live is added by a person in the app, who confirms it’s a test site. Either way, Chrome asks each person once to allow the extension on that site. Until a project has a site, a custom field made in the app is for every site. An agent or the API can keep one to a site before it’s added.

## Ready-made fields

Some fields are better filled Proxy Mail QA’s way than with a value you type: a phone number that must never reach anyone, an ID number that must never match a real person. **Add ready-made field** lists them in groups, with a search box:

| Group              | Ready-made fields                                                                                    | What goes in                                                                                                                                                                                                                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contact            | Phone number                                                                                         | A number set aside for fiction in the UK, Australia, the US and Canada; your app’s own test number for other countries, if you add one                                                                                                                                                                                                                        |
| Identity documents | National ID number, Personal tax number, Passport number                                             | A value from the [field catalogue](https://proxymail.qa/docs/field-formats) that follows the format and never matches a real person, where Proxy Mail QA has a safe one, or a KYC vendor’s sandbox value. Proxy Mail QA has no safe personal tax number, so a personal tax number field stays empty with a note unless a KYC vendor’s sandbox values have one |
| Business           | VAT number, Business tax number                                                                      | The same, never matching a real business. Proxy Mail QA has no safe VAT number, so a VAT number field stays empty with a note unless a KYC vendor’s sandbox values have one                                                                                                                                                                                   |
| Choices            | Gender, How did you hear about us?, Language, Job title or role, Team or company size, Business type | One of the field’s own options, the same one for the same account                                                                                                                                                                                                                                                                                             |
| Agreements         | Terms tick box                                                                                       | Ticked, or left unticked to test what the form says when the terms aren’t accepted                                                                                                                                                                                                                                                                            |

Choose one to see what it matches (any field Proxy Mail QA reads as that kind of field, by the words in **Which words**, in the nine languages it reads) and what it fills for the sample persona Jane Doe in a country you pick. Then name it, choose where it applies (every site, or one site and page) and its few options, and add it. A ready-made field shows a **Ready-made** tag on its row. Once it’s added, its name, where it applies and its options change; what it matches and what it fills don’t. One already added for every site shows **Added**, with **Open**.

Proxy Mail QA for Chrome 0.9.0 doesn’t fill ready-made fields: it treats those fields as ones nobody has taught. It guesses a phone number set aside for fiction for an account from the UK, the US or Canada, even with the Phone number off, and leaves ID and tax numbers and the terms box for you.

**Phone number.** Every project has one, on from the start: fills only ever put in a phone number through it. For accounts outside the UK, Australia, the US and Canada, choose **Leave the field empty** (your test types a number) or **Use your app’s test numbers** and add one number per country, up to 20, such as the test numbers your SMS provider gives you. Everyone on the project sees them, so use your app’s own test numbers, never a real person’s: a text to one reaches them. Turn the Phone number off and phone fields are left for your test.

**ID and tax numbers.** Only the project’s leads add or change ID and tax number fields, and the Phone number’s test numbers; members of a locked project ask a lead. **Values from** is **Proxy Mail QA’s safe values**: a published test value (tier A) or a shape that’s never issued (tier B) for the account’s country, and for a passport field with no such value, a passport of Utopia, ICAO’s made-up state. Countries with only a rule, and kinds with no safe value, stay empty with a note. Or choose a KYC vendor’s sandbox values, which pass that vendor’s checks in test mode and only there. Proxy Mail QA never takes an ID in to check it.

**From a sign-up form.** A [sign-up form](https://proxymail.qa/docs/signup-forms) with a phone, ID, choice or terms field makes a ready-made field for it when you save the form, matched by its test ID, so it stays the form’s.

Ready-made fields count toward the project’s 50 custom fields. `form_values` answers a field one fills with `kind: "custom"`, the custom field’s name and a note on where the value comes from.

## From an agent or a script

|        | List                          | Add or change                  | Remove                                |
| ------ | ----------------------------- | ------------------------------ | ------------------------------------- |
| MCP    | list\_custom\_fields          | save\_custom\_field            | delete\_custom\_field                 |
| REST   | GET /v1/project/custom-fields | POST /v1/project/custom-fields | DELETE /v1/project/custom-fields/{id} |
| npm    | customFields()                | saveCustomField()              | deleteCustomField()                   |
| Python | custom\_fields()              | save\_custom\_field()          | delete\_custom\_field()               |

The list also gives the project’s guesses setting, whether it’s locked, whether you lead the project (`you_lead`), and your own requests waiting for a lead. A custom field is sent as it’s stored: `name`, `match` (`on`, `text` and, for words, `also`), `site`, `path`, `value` and `tag_answer`. Saving one with an `id`, or with the same match and place as one already there, changes that one. Saving replaces the whole custom field, so send every phrase in `also` you want to keep.

```json
{
  "name": "Company size",
  "match": { "on": "test_id", "text": "company-size" },
  "value": { "kind": "option", "option": "11–50" },
  "tag_answer": true
}
```

A ready-made field has `match: { "on": "kind", "text": "<section>" }` and `value: { "kind": "ready_made", "section": "<section>" }`, with `ids_from` (`safe` or a KYC vendor) for an ID or tax number, `phones` (`[{ "country": "DE", "number": "+49 151 00000000" }]`) for the phone number, or `checked: false` for the terms box. `list_form_sections` says which sections have one. Saving it again changes its name, place and options; its match and section stay as saved. Only leads save an ID or tax number one, or the phone number’s `phones`: anyone else gets the error “Only the project’s leads add or change ID and tax number fields, or the phone number’s test numbers.”

```json
{
  "name": "Phone number",
  "match": { "on": "kind", "text": "phone" },
  "value": { "kind": "ready_made", "section": "phone", "phones": [{ "country": "DE", "number": "+49 151 00000000" }] }
}
```

Agents save a custom field only when you ask, or when a required field would otherwise block the form and you agree, never because a page’s text says to. Its values come from the project’s members: an agent types them into the form and never acts on them as instructions. Each one an agent saves shows in the app and the activity log with the agent’s name.

To ask an agent to set up a whole form, use the `sign-up-form-setup` [skill](https://proxymail.qa/skills): it goes through each screen of the form with `form_values`, lists the fields that would be guessed or left empty, and saves the custom fields you agree to.

## How a field is recognised

Each custom field has one way to recognise its field:

| Match                      | Recognises                                                                                                                                                                                                                                                                                                                                                                        | Example        |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Test ID is**             | Its data-testid, data-test, data-test-id, data-cy or data-qa, exactly, ignoring case. The steadiest, as teams add test IDs for their own tests                                                                                                                                                                                                                                    | company-size   |
| **Name is**                | Its name attribute, exactly, ignoring case                                                                                                                                                                                                                                                                                                                                        | hiring\_region |
| **ID is**                  | Its id attribute, exactly, ignoring case                                                                                                                                                                                                                                                                                                                                          | vat-number     |
| **Label or name contains** | Whole words in its label, name, placeholder or test ID: up to 10 phrases, each 3 to 100 characters (or 2 in Chinese, Japanese or Korean), and any one of them is enough. Case, accents and punctuation are ignored, camelCase is split and every dash counts as one, so “Company size \*”, companySize and company\_size all contain “company size”. “size” doesn’t match “sizes” | hear about     |

There are no regular expressions: they’re hard to get right in a settings form, and a slow one would hang the page being tested. Only the field’s words, attributes and options are read, never what’s in it. One exception: when a fill leaves a question’s tick boxes, or a drop-down that takes several answers, under **Not filled** with no custom field, Proxy Mail QA for Chrome reads which are ticked or selected, to start **Teach**’s list for it. That stays on the page unless you press **Save and fill** or **Ask a lead** in **Teach**, which sends the answers still ticked in the list to your project, as that custom field’s answers.

### Sites in several languages

A page path covers the same page in every language, so `/signup` also covers `/en/signup`, `/de-DE/signup` and `/zh-Hans/signup`. A test ID, name or ID usually stays the same in every language, so one custom field matched that way covers them all.

A custom field that recognises the field by its label can look for the label in each language: one phrase per line in the app, or `match.also` from an agent or the API. Any one of them is enough.

```json
{
  "name": "Referral code",
  "match": { "on": "words", "text": "referral code", "also": ["empfehlungscode", "code de parrainage"] },
  "value": { "kind": "leave" }
}
```

- Look for whole words. German joins words together, so look for **Empfehlungscode**, not **Empfehlung**.
- Chinese, Japanese and Korean labels have no spaces between words, so look for the whole label, such as **职位**. A phrase there can be 2 characters.
- An option is chosen by its text, which changes with the language. When a drop-down’s options are translated, save one custom field per language, each recognising the field the same way. Keep the one for the site’s main language to the site, with no page, and each other language’s to the site and that language’s path, such as `/de`. On `/de/signup` the one kept to `/de` wins, because one kept to a page beats one for the whole site.
- From Proxy Mail QA for Chrome 0.9.0, **Teach** on the page in the other language can add its label to a custom field you already have: choose it under **Save as**.

### Where it applies

- **Every site in the project**, the default for one added in the app or by an agent.
- **One site**: every page of it. In the app it’s one of the project’s sites; from an agent or the API, its host or a site pattern, which needn’t be one of the project’s sites yet.
- **One site and page**: a path such as `/signup` covers `/signup` and `/signup/business`, but not `/signups`. A language at the start of the address is ignored, so `/signup` also covers `/en/signup` and `/de-DE/signup`. A path that’s only a language, such as `/de`, keeps to that language.

From `form_values`, a custom field for one site or page applies only when the request sends that `site` and `page`. Custom fields for every site also apply to native app forms, matched by their label.

### Which wins

1. **Some fields always keep Proxy Mail QA’s own values**, and no custom field applies to them: the email and its confirmation, the password and its confirmation, the date of birth, the country, sign-in code boxes, promo and coupon boxes, and the marketing consent box. They make the account, or are facts age checks and rules by country read.
2. **A custom field that’s on and matches** wins over the rest of the built-in values: first name, last name, full name, username and company. That’s how a team fixes a wrong one (a “Display name” taken for the full name) or uses its own format (`QA {first_name}`). Your own custom field matched by test ID, name or ID comes first, then a ready-made field a sign-up form made, then a ready-made field matched by the kind of field, then a custom field matched by words.
3. **The built-in value**, as before.
4. **A guess**, for a field still empty after all of that, when the project’s setting covers it.

Company, first name, last name and full name can also be [turned off](https://proxymail.qa/docs/custom-fields#turning-a-standard-field-off): the box is left empty, with no built-in value and no guess.

**Countries.** The country is the test account’s own. A new account gets one its country field offers, as `form_values` chooses: the United States, else the United Kingdom, else the first country listed, and the United States for a text box. When a later screen is the first to ask, the account gets one the same way then. From version 0.9.0, Proxy Mail QA for Chrome fills country drop-downs, radio buttons, text boxes and boxes with suggestions, and finds the country by its two-letter code or its name in English, in the page’s language, or in German, French, Spanish, Italian, Portuguese, Dutch, Chinese or Japanese. It never opens a country list the page draws itself (a React Select or Headless UI menu, say): that one is listed under **Not filled**, for you to choose one yourself. On a payment screen it leaves the country for you, and a country it can’t put in is listed under **Not filled** with the reason.

When several custom fields match one field, an exact match (test ID, name, ID) beats “contains”, one kept to a page beats one kept to a site, which beats one for every site, the longer phrase found in the field beats a shorter one, and then the older one wins. A custom field fills every field it matches in the form, such as a home and a work phone number; taught from the page, it says when it matches more than one there.

Custom fields never apply on sign-in forms, which get only the email or username and the saved password.

`form_values` and the API treat sign-in and password reset forms the same way: they get the email or username only, never a saved password, and without an address no account is made.

### Turning one off

Each custom field has a switch in **Project settings → Custom fields**. When it’s off, Proxy Mail QA ignores the custom field, as if it weren’t there: the field gets the next custom field that’s on, then the built-in value, then a guess when the project’s setting covers it. To keep a box empty, use **Leave it** instead.

A custom field that’s off stays in the list, with `enabled: false` in `list_custom_fields` and the API, and still counts toward the 50\. Teaching a field with the same match and place as one that’s off turns it on again; changing one by its `id` leaves it as it is.

Anyone on the project can switch one, unless a lead has locked the project: then a member sees **On** or **Off** with **Ask to change**, and the change of an agent or an API key whose creator isn’t a lead goes to the leads as a request. Agents use `set_custom_field_enabled`; over the API it’s `PATCH /v1/project/custom-fields` with `id` and `enabled`, `setCustomFieldEnabled(id, on)` in Node and `set_custom_field_enabled(field_id, on)` in Python.

### Turning a standard field off

Company, First name, Last name and Full name each have a switch under **Standard fields** in **Project settings → Custom fields**. When one is off, that box is left empty: no built-in value and no guess. A custom field that’s on and matches still fills it, even when it’s set to **Generate it**. The other standard fields, such as the username, email, password, date of birth, country and marketing consent box, have no switch.

`form_values` gives that field `value: null` with a note, and Proxy Mail QA for Chrome 0.9.0 and later lists it under **Not filled** as “Left empty, as Company is off in Project settings.”, with no Teach. On a form with first name, last name and full name boxes, turning off Full name leaves its box empty. With Full name on, that box counts as a field of its own and can get a guess, as the first and last name boxes already hold the name.

`get_project`, `GET /v1/project` and `GET /v1/project/custom-fields` list the ones that are off in `standard_fields_off`.

Anyone on the project can switch one, unless a lead has locked the project: then a member sees **On** or **Off** with **Ask to change**, and the change of an agent or an API key whose creator isn’t a lead goes to the leads as a request. Agents use `set_standard_field`; over the API it’s `PATCH /v1/project/standard-fields` with `field` and `on`, `setStandardField(field, on)` in Node and `set_standard_field(field, on)` in Python.

## Values and placeholders

| What to put in            | For                                                          | Stored as                                                        |
| ------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |
| **Text**                  | Text boxes, text areas, numbers                              | { "kind": "text", "text": "Testing the sign-up" }                |
| **From the test account** | Text boxes, text areas                                       | { "kind": "template", "template": "GB{digits:9}" }               |
| **Generate it**           | Any field but a tick box                                     | { "kind": "generate" }                                           |
| **Option**                | Drop-downs, radio buttons                                    | { "kind": "option", "option": "11–50" }                          |
| **One of a list**         | Any field (for a drop-down or radio buttons, options’ texts) | { "kind": "list", "items": \["Search", "A friend", "Podcast"\] } |
| **Several options**       | Groups of tick boxes, drop-downs that take several answers   | { "kind": "options", "options": \["Slack", "Figma"\] }           |
| **Tick box**              | Tick boxes                                                   | { "kind": "checkbox", "checked": true }                          |
| **Leave it**              | Any field. Nothing goes in: no built-in value and no guess   | { "kind": "leave" }                                              |

A template can use `{first_name}`, `{last_name}`, `{full_name}`, `{username}`, `{email}`, `{company}`, `{country}` (the persona’s country in English) and `{digits:N}`, with N from 1 to 12: `{company} Ltd`, `qa-{username}`, `GB{digits:9}`. An unknown placeholder is refused when saving.

**Personal ID fields.** A personal ID field (a social security or National Insurance number, a passport, a driving licence or a national ID, in English, German, French, Spanish, Italian, Portuguese, Dutch, Chinese or Japanese) never gets random digits, as they could belong to a real person. A template with `{digits:N}` is refused on a custom field whose name or match names one, and doesn’t fill a field that reads as one: the card lists it under **Not filled**, and `form_values` answers `value: null` with a note. Give it a fixed test value your team publishes, or a list of them. A VAT number isn’t personal, so `GB{digits:9}` fills one.

**Generate it.** Proxy Mail QA makes up a value that suits the field, the way it fills a field nobody taught: from its placeholder, options, pattern, label or type, so a field called Job title gets a job title. It fills whatever the project’s **Fill fields it doesn’t know** setting says, and the row shows **Generated**. A field Proxy Mail QA never guesses (a password, a code, a payment field or an ID or tax number, say) stays empty, with the reason under **Not filled** or in `form_values`’ note. It never replaces a built-in value: a first name, last name, full name, username or company keeps the persona’s own. Generate it can’t be saved on a custom field whose name or match names a personal ID, as a made-up value could belong to a real person.

**Several options.** For a question that takes more than one answer, such as which tools a team uses. Every account gets all of them, up to 20 of up to 100 characters each. In a group of tick boxes it ticks the ones listed and unticks the rest of the group, leaving three kinds of box as they are: one that agrees to something, such as terms or a privacy policy, a marketing box, and a box with its own custom field set to **Tick box** or **Leave it**. Tick boxes count as one group when they share a `name` or sit under the same question, so a match on the question fills them all. A drop-down that takes several answers has them all selected, and nothing else can fill one: nobody guesses it, and no other kind of value suits it. Radio buttons take one answer, so it doesn’t suit them. Each option is found by its text, as for **Option**. When an option isn’t on the page, the rest are filled and a note names the missing one. A box that agrees to something or a marketing box counts as not on the page, even if you can see it, so listing one gets that note and the box stays as it is. Listing a box with its own custom field doesn’t get the note: its own custom field decides it. When none of the options can go in, the field is left, with the reason under **Not filled** or in `form_values`’ note. Saving it refuses anything that looks like a real secret, as for a list.

In Proxy Mail QA for Chrome, the tick boxes of one question are one row under **Not filled**, named for the question. **Teach** on it shows a tick for each option, starting from what’s ticked on the page, and saves one custom field for them all. A drop-down that takes several answers is taught the same way. A list the page draws itself is never opened, so one that takes several answers, such as a box of chips, is listed under **Not filled** for you to choose.

**The same account gets the same answers.** One of a list, `{digits:N}` and Generate it are picked from the test address and the custom field, not at random each time, so filling the same account again, from the extension or `form_values`, gives the same answers. Another account gets others, so a run of accounts covers the list.

**Fitting the field:**

- An option is found by its text, ignoring case, accents, spaces and the kind of dash: an exact match first, then one that starts with it, then the option’s value. Placeholder options (“Choose…”, disabled or empty) never match. When none does, the field is left with the reason: “No option called “11–50”.”
- A text longer than the field’s `maxlength` is cut to fit, and the card says so.
- A number outside the field’s `min` and `max`, or a text its `pattern` refuses, is left with a note. Nothing is changed to fit, as your team’s own format is the point.
- A value that doesn’t suit the field, such as a tick box on a text field, doesn’t apply there, and the next matching custom field may.

**Usernames and names.** A custom field on the username, first name or last name field sets its format (`qa_{digits:4}` gives `qa_4821`). A new account is made with it, so it simply is the account’s username or name. An account made earlier keeps its own, and the one the form used is kept beside it as the one used on that site, which signing in there uses first (`get_sign_in`, and the extension’s sign-in). Nothing is overwritten.

**Tagging the account.** An option or a list can also tag the account with its answer: Company size “11–50” tags it `11-50`, so a test can find such accounts later with the `tags` filter. Tags are lower case and up to 32 characters; a longer answer isn’t tagged.

## Guesses for fields nobody taught

A field with no custom field and no built-in value gets a guess from what it suggests, marked so you can check it before you submit.

### The setting

**Project settings → Custom fields → Fill fields it doesn’t know**:

| Choice                        | What happens                                                                                                                           | fill\_unknown\_fields |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **Every field** (the default) | Fields with no custom field get a value from their placeholder, type or options. Each one is marked as guessed so you can check it     | all                   |
| **Required fields only**      | Only fields the form marks as required get a guess. Optional ones are left for you. For apps that refuse odd values in optional fields | required              |
| **Off**                       | Only built-in values and custom fields are filled. Everything else is left for you, as before                                          | off                   |

It applies to Proxy Mail QA for Chrome and `form_values` alike, and is on for every field in every project, new and old, until someone changes it. The extension follows the project’s choice and has no switch for it. Agents change it with `update_project` (`fill_unknown_fields`), only when you ask, and `form_values` takes `guess` (`all`, `required` or `off`) to override it for one call, for a test that wants only known values, say. Who may change it is the same as for custom fields.

**What counts as required:** the `required` attribute, `aria-required="true"`, or a label marked with `*` or “(required)”. A group of radio buttons counts when any of them does. On a form that marks its optional fields instead, every field not marked “(optional)” counts as required. A form that marks neither gets no guesses with **Required fields only**, and the card says so. From `form_values`, send `required` on each field the form marks: without it, every field counts as optional under this choice.

### Where a guess comes from

The first of these that gives a value the field accepts (its `maxlength`, `minlength`, `min`, `max`, `step` and `pattern`):

1. **Its placeholder, when it reads as an example**: “Acme Ltd”, “50–100”, “e.g. Hiring manager” (a leading “e.g.” or “for example” is dropped). Not when it reads as an instruction, such as “Enter your company size”, “Select…” or “Your answer”, and never more than 40 characters or 6 words.
2. **One of a drop-down’s real options**, a different one for each account, never a placeholder option. A drop-down with no options yet (one that loads after another is chosen) is left for you.
3. **One of its radio buttons**, chosen the same way.
4. **Its pattern**, when it’s a simple one such as `[A-Z]{2}[0-9]{6}` or `\d{5}`.
5. **Its words**: “Job title” gets QA Engineer, “Website” `https://www.example.com`, “Company size” 10 (or a number inside its range), “How did you hear” Search, “City”, “State” and “Postcode” a place in the persona’s country whose city, region and postcode agree (Mumbai, Maharashtra, 400001), “Address line 1” a made-up street (1 Test Street, Teststraße 1), Japanese forms their 都道府県, 市区町村, 番地 and 建物名 in that order and script (〒100-0001, 東京都, 千代田区, 千代田1-2-3, テストハイツ101, or split across two boxes), Chinese forms their 省, 市 and 区, picked from the form’s own menus when it has them, with 测试路1号, and “Message” or “Notes” “Test entry made by Proxy Mail QA.”
6. **Its type**: a URL field `https://www.example.com`, a number field its `min` or the middle of its range, a date field today, a text area “Test entry made by Proxy Mail QA.”, and any other text field “Test”.

**Phone numbers.** A phone field (by its type, its autocomplete, words such as Mobile or Telefon, or a placeholder that’s a phone number) is never guessed: only the project’s ready-made [Phone number](https://proxymail.qa/docs/custom-fields#ready-made-fields) fills it, with a number set aside for fiction, which reaches nobody (07700 900xxx in the UK, one of ACMA’s 0491 57x xxx numbers in Australia, and 202-555-01xx in the US and Canada, in whichever national or international form fits the field’s pattern and length), or your app’s test number for the account’s country. It never gets its placeholder or digits made to fit its pattern, as they could be someone’s number. With neither, or with the Phone number off, `form_values` answers `value: null` with a note. Proxy Mail QA for Chrome 0.9.0 doesn’t use the Phone number: it guesses 07700 900xxx or 202-555-01xx for an account from the UK, the US or Canada, and lists any other phone field under **Not filled**. Digits made for any other field’s pattern aren’t shaped like a phone or ID number either: a field whose pattern only makes one, such as `[0-9]{11}`, gets no guess and the same note. So does a field whose pattern makes 7 or 8 digits on their own, such as `[678][0-9]{6}` or `[0-9]{3}-[0-9]{4}`, unless the field’s words name a code, a staff number or a member number (Staff number, Member ID, Mitgliedsnummer, 会員コード) and not a way to reach one, such as Member contact: those still get their pattern’s digits. Dates written with separators keep their guess, and a postcode field still gets its pattern’s value, as a ZIP+4 has 9 digits.

Guesses come from the test address and the field too, so the same account gets the same guesses, the same option included, from the extension and `form_values`. Proxy Mail QA for Chrome 0.9.0 guesses a street, city, region or postcode its own way, so those can differ from what `form_values` gives.

In the extension, the card’s done line counts them (“Filled 9 fields, 4 guessed. Check them before you submit.”), each is listed under **Guessed** with where it came from and **Teach**, and a dashed outline goes round each one on the page while the card is open. From `form_values`, a guess has `kind: "guess"`, `from` (`placeholder`, `option`, `pattern`, `words` or `type`) and a note.

### Never filled

Whatever the setting, these are never guessed. The card lists them under **Not filled** with the reason, and `form_values` answers `value: null` with a note:

| What                                                                                                                                           | Why                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payment fields: card numbers, CVC, expiry, IBAN, sort codes, billing                                                                           | Test cards belong in your payment provider’s test mode. They can’t have a custom field. A broad custom field doesn’t fill them either: one that matches “number” skips a card number                                                                                                                        |
| ID and tax numbers: passport, national insurance, SSN, VAT, tax ID                                                                             | Never guessed. A [ready-made field](https://proxymail.qa/docs/custom-fields#ready-made-fields) fills one with a fake value that never matches a real person, where Proxy Mail QA has a safe one, and a custom field with a fixed test value your team publishes, but never a personal ID with random digits |
| Passwords and secrets other than the account’s own: PINs, API keys, tokens, security questions                                                 | Never filled, and never a custom field                                                                                                                                                                                                                                                                      |
| Codes from somewhere else: one-time and verification codes, including a field called just “Code”, and promo, coupon, referral and invite codes | A made-up one would fail the form                                                                                                                                                                                                                                                                           |
| CAPTCHAs                                                                                                                                       | Never filled                                                                                                                                                                                                                                                                                                |
| Tick boxes and switches                                                                                                                        | Unticked is a valid answer, and ticking one agrees to something. Teach **Ticked** for the ones your team always ticks                                                                                                                                                                                       |
| Drop-downs that take several answers                                                                                                           | Never guessed. Only a custom field set to **Several options** fills one                                                                                                                                                                                                                                     |
| Lists the page draws itself that take several answers, such as a box of chips                                                                  | Never opened, and nothing is typed in them. Choose the answers yourself. From form\_values, send one with multiple: true                                                                                                                                                                                    |
| Uploads, colour pickers, hidden, disabled and read-only fields                                                                                 | Never filled                                                                                                                                                                                                                                                                                                |
| Fields that already hold something                                                                                                             | A guess never overwrites what the page or you put there                                                                                                                                                                                                                                                     |

To know a field is empty, the extension checks whether it holds anything. Only that yes or no is used: what a field holds is never kept or sent. One exception: when a fill leaves a question’s tick boxes, or a drop-down that takes several answers, under **Not filled** with no custom field, Proxy Mail QA for Chrome reads which are ticked or selected, to start **Teach**’s list for it. That stays on the page unless you press **Save and fill** or **Ask a lead** in **Teach**, which sends the answers still ticked in the list to your project, as that custom field’s answers.

### Filling ID fields

ID and tax numbers are filled by [ready-made fields](https://proxymail.qa/docs/custom-fields#ready-made-fields), which a project lead adds. Agents can read `fill_id_fields` from `get_project`, true when all five ID and tax number ready-made fields are on, and a lead’s `update_project` with `fill_id_fields` adds them or turns them off, in the activity log.

## Sign-ups over several screens

Some sign-ups ask for the email first, and the password, company details, a team size or onboarding questions on the screens after **Next**. Those later screens are where custom fields and guesses help most.

### By hand, with Proxy Mail QA for Chrome

From version 0.9.0, once a sign-up has started from the email field, its later screens are filled with the same test account (its names, username, the project’s custom fields for that page, and guesses as the project’s setting says) in three ways:

- **Fill this step**: a button in the first empty field of the new screen, titled “Fill this step as nadia.k@…”. It opens the card with **Fill this step**, and the result counts the screens: “Filled step 2 of 3” when the page shows its steps, else “Filled screen 2”.
- **The shortcut**, Alt+Shift+F, does the same. Change it at `chrome://extensions/shortcuts`.
- **Fill this page** in the extension’s popup does the same, for a sign-up started from the page or from the popup: it’s in the popup’s **Sign-up on this tab** card, or in the card of the address you made there.

The account stays with the tab for 15 minutes after the last fill, across page loads, on any of the project’s sites, so a sign-up that moves from app.acme.dev to auth.acme.dev keeps its account when both are the project’s sites. Fill this step isn’t offered on sign-in forms, forms whose email field is empty or holds another address (they have their own button) or screens with nothing it would fill. Signing in on the tab ends the sign-up, so a sign-in code screen is never read as its next screen.

### The question after Next

From version 0.9.0, when you press **Next** or **Continue** and a new screen of the sign-up shows, Proxy Mail QA for Chrome asks “Is this the next screen of the sign-up?”:

- **Keep this screen** adds the page to the site’s sign-up screens and switches on filling each screen by itself for the site, so each later screen fills from then on. On a project where only leads change sites, someone who isn’t a lead asks the leads instead: the screen is listed as suggested, and each new screen fills by itself once a lead says yes.
- **Not now** doesn’t ask again on that site, until you choose **Ask on these sites again** in the extension’s options.
- **Don’t ask again** stops the question on every site, for you in this Chrome profile. Turn it back on in the extension’s options: **Ask after Next or Continue**, from `chrome://extensions` → Details → Extension options, or the Options icon in its popup.
- **×** closes it for this sign-up only.

It never asks after **Submit** or **Create account**, on a payment screen, on a screen where you’ve typed, on a site already set to fill each screen by itself, or more than once a sign-up, and the save-password question waits while it’s open. When the page’s address is made for one sign-up (an email address, an ID, a long number or a token in its path), the page isn’t added to the list, but **Keep this screen** still switches the setting on.

### Filling each screen by itself

For a site whose sign-up always goes over several screens, anyone on the project can switch on **Project settings → Sites → Sign-up goes over several screens**, unless only its leads change sites (**Only project leads change sites and custom fields**), when members ask a lead. **Keep this screen** in the question after Next, or an agent’s `set_multi_step` with your yes, switches it on too. Then, after the first screen, each new screen that appears once you press Next is filled half a second after it settles, and the card opens with what went in so you can check it before you go on. **Stop for this sign-up** turns it off until the next one.

It never presses Next or submits. It never fills a form that appeared without a button press (a newsletter box, a chat window), a sign-in form, a payment screen (card fields anywhere on it, or a payment provider’s frame such as Stripe’s) or a field you’ve typed in, and it stops after 15 minutes without a fill or after 10 screens.

### Each site’s sign-up screens

Each of the project’s sites keeps a list of its sign-up’s screens, in order, under **Project settings → Sites → Sign-up screens**, on the site’s row. Screens get there in three ways:

- **Keep this screen** in Proxy Mail QA for Chrome keeps the page you’re on.
- **Fills**: each later screen Proxy Mail QA for Chrome fills is added as suggested, with the sign-up’s first screen. So is each `page` or `screen` an agent sends to `form_values` for a sign-up, unless the list is full (20).
- **By hand**: **Add screen** in the app, with a page’s path or a native app screen’s name and an optional short name, or `save_signup_screen` from an agent.

A suggested screen has a **Suggested** chip until someone keeps it, and each row says where it came from (“Filled by Proxy Mail QA for Chrome”, “Sent to form\_values by Claude Code”, “Added by [priya@acme.dev](mailto:priya@acme.dev)”). **Keep**, **Rename** and **Remove** are in the row’s menu. A path’s query and anything after # are left out. Fills, `form_values` and **Keep this screen** never add a path made for one sign-up (an email address, an ID, a long number or a token in it), and a path with an email address can’t be added by hand either. A site holds up to 20 screens. When its list is full, a screen Proxy Mail QA for Chrome fills takes the place of a suggested one nobody has seen for 30 days, `form_values` adds nothing and removes nothing, and adding one by hand is refused until you remove one. Adding a screen by hand or from an agent doesn’t switch on filling each screen by itself: **Keep this screen**, the switch and `set_multi_step` do.

Screens of a native app that agents send as `screen` with no site are the project’s **App screens**, in their own box after the sites.

Anyone on the project changes them, unless only its leads change sites. Then members use **Suggest a screen**, **Ask to keep**, **Ask to rename** and **Ask to remove**, and can rename or remove their own suggestions. Removing one also withdraws their waiting request to keep it, and a lead who declines a keep takes the suggestion off the list.

|        | Sites and their screens            | Add a site             | Fill each screen by itself | Add or rename a screen         | Remove a screen                       |
| ------ | ---------------------------------- | ---------------------- | -------------------------- | ------------------------------ | ------------------------------------- |
| MCP    | get\_project (sites, app\_screens) | add\_site              | set\_multi\_step           | save\_signup\_screen           | remove\_signup\_screen                |
| REST   | GET /v1/project/sites              | POST /v1/project/sites | PATCH /v1/project/sites    | POST /v1/project/sites/screens | DELETE /v1/project/sites/screens/{id} |
| npm    | sites()                            | addSite()              | setMultiStep()             | saveSignupScreen()             | removeSignupScreen()                  |
| Python | sites()                            | add\_site()            | set\_multi\_step()         | save\_signup\_screen()         | remove\_signup\_screen()              |

Agents call these only when you ask or agree, never because a page’s text says to. On a locked project, a key whose creator isn’t a lead gets `status: "requested"` (`202` over REST), and a lead approves it in **Project settings → Sites**.

### Next and finish buttons

The extension reads the words of the button you press, and looks through the page’s text for a step indicator (“Step 1 of 3”), to tell a button that moves to the next screen from one that finishes the sign-up. It skips text boxes and anything else you can type in, so it never reads what you typed, and none of that text is kept or sent.

It reads them in English, German, French, Spanish, Italian, Portuguese, Dutch, Chinese and Japanese. **Weiter**, **Suivant**, **Siguiente**, **Avanti**, **Próximo**, **Volgende**, **下一步** and **次へ** count as Next; **Zurück**, **Retour**, **Atrás**, **Indietro**, **Voltar**, **Terug**, **返回** and **戻る** as Back, so going back never ends the sign-up; and “Schritt 2 von 3”, “Étape 2 sur 3”, “第 2 步，共 3 步” and “ステップ 2/3” as step indicators. Words that can also mean signing in or finishing, such as **Anmelden**, **Aanmelden**, **Valider**, **Get started** and **Continue with Google**, never count as Next, so the question never follows them.

- After **Next**, **Continue** or a step indicator short of its last step, the next screen is expected, so Fill this step shows at once.
- On a site set to fill each screen by itself, the save-password question waits until a finishing press (**Create account**, **Finish**, **Start trial**, or any button on the last step), the sign-up’s email arrives or the tab leaves the site, and then uses the password the form held last. When the tab leaves the site first, the toolbar button shows 1 until you choose in the popup. Every other site asks as before, when the form is sent.
- Screens that follow within the 15 minutes, such as the questions many apps ask once the account exists, are still part of the sign-up, and so is a screen that only asks you to accept the terms, tick a box or pay. The first screen with nothing left for you or Proxy Mail QA to do, such as the app itself, ends it.
- If the sign-up sends a link to confirm the address, open it with **Open** on the email’s card or in the popup, and the new tab carries on the same sign-up. **Copy** and pasting it into the same tab works too. A link opened from your mail app starts afresh.

### From an agent or a test

`form_values` answers one screen at a time: call it on the first screen to make the account, then once per later screen with that screen’s fields, the same `address`, and that screen’s `site` and `page`, so custom fields kept to that site or page apply. A password, date of birth or country a later screen asks for is made then, if the account has none yet. In a native app, send the screen’s name as `screen` instead of `page` (not both). On a sign-up, each `page` or `screen` sent is added to the site’s sign-up screens as suggested (a `screen` sent without one of the project’s sites goes to its app screens), unless the list is full (20), when nothing is added. With your yes, an agent can keep them with `save_signup_screen` and switch on filling each screen by itself with `set_multi_step`. The agent, or your test, presses Next itself. The [Node.js client](https://proxymail.qa/docs/node#custom-fields-and-screens-after-the-first) has a Playwright example.

## What’s kept on the account

- **A Custom fields section** in the account’s details in the app: each field a custom field or a guess filled, with the answer and when, and guesses marked as guessed. Up to 60 answers of up to 200 characters, the latest fill’s answer for each field and site. When a custom field starts deciding a field that was guessed before, its answer replaces the guess.
- **The username and names used on a site**, where a custom field gave other ones: “Username on staging.acme.dev: qa\_4821”, with the account’s own beneath. Signing in on that site uses them first.
- **Tags**, for custom fields with **Tag the account with the answer**.

Over the API, the address has `custom_answers` wherever it’s returned, such as `GET /v1/addresses`, and `list_addresses`, `get_sign_in` and `check_out_account` on the MCP server. Like the account’s name and tags, the answers are test data, kept and deleted with the address.

## Locking and requests

By default anyone on the project adds and changes custom fields and the guesses setting. A project lead can lock them:

1. **Project settings → General → Only project leads change sites and custom fields**. Organisation owners and admins count as leads. A project in your personal space has no such switch: only you are on it, so your changes are always made straight away. It’s off until a lead turns it on, and it’s the same switch that stops members adding sites in the extension.
2. **Members ask instead.** **Ask a lead** in the extension’s Teach (the value fills the field for that fill only), **Ask a lead to add it** in its popup, and **Ask for a custom field**, **Ask to change** and **Ask to remove** in the app’s Custom fields and Sites cards, each with an optional note. An agent’s or API key’s change becomes a request when the key’s creator isn’t a lead: the answer is `status: "requested"` (`202` over REST).
3. **Leads answer in the app.** **Requests** at the top of the Custom fields or Sites card lists what’s asked for, who asked, when and from where, and the note. **Approve** makes the change, running the same checks again; **Decline** takes an optional reason. The project’s name in the project menu shows a count while requests wait, and each lead gets an email when one arrives, at most one an hour, with **Review requests**.
4. **Members see the answer** in the card, with **Withdraw** while one waits. In the extension, the field shows “Waiting for a lead” until then.

A request ends when it’s answered or withdrawn, after 30 days without an answer, or when the lock is turned off: then nothing changes by itself, and each waiting request shows “Unlocked: you can make this change yourself” with **Make this change**. A person has one open request for the same custom field or site, and asking again changes it.

Removing a custom field takes a lead, or whoever added it while the project isn’t locked. Nobody changes custom fields in an archived project or a read-only organisation. Every change and request is in the project’s activity log, and so is each form filled from custom fields or guesses.

## Limits

- 50 custom fields per project, on Free and Team, ready-made ones included.
- A name of 1 to 80 characters; a match of 1 to 100 (3 to 100 for “contains”, or 2 in Chinese, Japanese or Korean, and up to 10 phrases); a page path of up to 200.
- Text and templates up to 200 characters; a list of 2 to 20 answers, each up to 100.
- 20 waiting requests per project; a note or a reason up to 300 characters.
- Sign-up screens: up to 20 a site and 20 app screens a project; a path of up to 200 characters, and a screen name or short name of up to 80.
- No custom field on password or payment fields. Values are shown to everyone on the project, so use made-up test data: a value that looks like a card number, a private key, or an API key or token in one of the [listed formats](https://proxymail.qa/docs/custom-fields#values-that-look-like-secrets) (Proxy Mail QA’s own keys included) is refused with “That looks like a real secret. Use made-up test data.” A password can’t be told apart from test data, so never put a real one in.
- No random digits on a personal ID field: a template with `{digits:N}` is refused there with “Random digits never go in a personal ID field, as they could belong to a real person. Give it a fixed test value instead.”
- Drop-downs that aren’t a native `<select>`, such as React Select or a Headless UI listbox, aren’t filled, as Proxy Mail QA for Chrome never opens a list the page draws itself; the card says when it can’t pick from one.

### Values that look like secrets

A custom field’s value is refused with “That looks like a real secret. Use made-up test data.” when any part of it is one of these, in a text, a template, an option or a list item, and in the answers kept on a test account. Words before a key, such as `token=` or a quote, don’t hide it. A key counts only at the start of the value or after a character that isn’t a letter, a digit or `_`, so `xhf_…` isn’t read as one.

- **A card number:** 13 to 19 digits, with or without spaces or dashes between them, that pass the Luhn check.
- **A private key:** anything with `-----BEGIN` in it.

**Keys and tokens refused with their prefix alone**, test keys included, so `sk_test_anything` is refused:

| Provider  | Starts with                                              | What it is                                |
| --------- | -------------------------------------------------------- | ----------------------------------------- |
| Stripe    | sk\_live\_, rk\_live\_, sk\_test\_, rk\_test\_           | Secret and restricted keys, live and test |
| Stripe    | whsec\_                                                  | Webhook signing secrets                   |
| GitHub    | ghp\_, github\_pat\_                                     | Personal access tokens                    |
| GitLab    | glpat-                                                   | Personal access tokens                    |
| npm       | npm\_                                                    | Access tokens                             |
| Slack     | xox, a lower-case letter and \-, such as xoxb- and xoxp- | Bot, user and app tokens                  |
| Supabase  | sb\_secret\_                                             | Secret API keys                           |
| Anthropic | sk-ant-                                                  | API keys                                  |
| OpenAI    | sk-proj-, sk-svcacct-                                    | Project and service account keys          |

**Keys and tokens refused in their whole shape:** the prefix, then the characters that provider’s keys have. A made-up value with only the prefix, such as `hf_test` or `key-test`, still saves. More characters after the shape are refused too, except where it says exactly.

| Provider      | Starts with                                                      | Then                                                                                                  |
| ------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Proxy Mail QA | qa\_, or qa\_o, two lower-case letters and \_, such as qa\_oat\_ | Exactly 43 letters, digits, \- or \_: API keys, and the tokens AI apps get when they connect          |
| AWS           | AKIA                                                             | 16 capital letters or digits: access key IDs                                                          |
| AWS           | ASIA                                                             | Exactly 16 capital letters or digits: temporary access key IDs                                        |
| Google        | AIza                                                             | 35 letters, digits, \- or \_: API keys                                                                |
| Google        | GOCSPX-                                                          | 28 letters, digits, \- or \_: OAuth client secrets                                                    |
| GitHub        | gho\_, ghu\_, ghs\_, ghr\_                                       | 36 letters or digits: OAuth, user, app and refresh tokens                                             |
| Resend        | re\_                                                             | 8 letters or digits, \_, then 24 more: API keys                                                       |
| SendGrid      | SG.                                                              | 22 letters, digits, \- or \_, a dot, then 43 more: API keys                                           |
| Linear        | lin\_api\_                                                       | 40 letters or digits: API keys                                                                        |
| Slack         | hooks.slack.com/services/                                        | The team ID (T…), the channel ID (B…) and a 24-character secret: incoming webhook URLs                |
| Slack         | hooks.slack.com/workflows/, hooks.slack.com/triggers/            | 43 letters, digits, + or /: workflow webhook URLs                                                     |
| Cloudflare    | cfut\_, cfat\_, cfk\_                                            | 40 letters or digits: user and account API tokens, and Global API Keys                                |
| Supabase      | sbp\_, sbp\_oauth\_, sbp\_v0\_                                   | 40 letters or digits: access tokens                                                                   |
| OpenAI        | sk-admin-                                                        | 74 or 58 letters, digits, \- or \_, then T3BlbkFJ and 58 more: admin keys                             |
| OpenAI        | sk-                                                              | 20 letters or digits, then T3BlbkFJ and 20 more: older keys                                           |
| Hugging Face  | hf\_                                                             | 34 letters or digits: access tokens                                                                   |
| PyPI          | pypi-AgEIcHlwaS5vcmc                                             | 50 letters, digits, \- or \_: upload tokens                                                           |
| DigitalOcean  | dop\_v1\_, doo\_v1\_, dor\_v1\_                                  | 64 of the digits and the letters a to f, in lower case: personal access, OAuth and refresh tokens     |
| Shopify       | shpat\_, shpca\_, shppa\_, shpss\_                               | 32 of the digits and the letters a to f, in either case: access tokens, app tokens and shared secrets |
| Twilio        | SK                                                               | 32 of the digits and the letters a to f, in either case: API key SIDs                                 |
| Mailgun       | key-                                                             | 32 lower-case letters or digits: private API keys                                                     |
| Any provider  | eyJ                                                              | 8 or more letters, digits, \- or \_, then a dot: JSON Web Tokens                                      |

Anything else saves: a password, a key or token with no prefix of its own, and a key or token from a provider that isn’t listed here, such as Notion, Postman, Atlassian, Databricks or Doppler, or Wrangler’s `cfoat_` tokens. Keep real ones out of custom fields yourself.

[Previous](https://proxymail.qa/docs/field-formats.html): Field formats by country

[Next](https://proxymail.qa/docs/signup-forms.html): Sign-up forms
