---
title: "Sign-up forms: save your form as a spec | Proxy Mail QA"
description: "Save your sign-up form as a spec, its screens and fields from the field catalogue, in the app, with your coding agent or the API. Proxy Mail QA makes the custom fields it needs and gives the form back as React or HTML, with tests."
url: https://proxymail.qa/docs/signup-forms
---

# Sign-up forms: save your form as a spec

A sign-up form spec says what your form asks for, screen by screen: each field’s section from the [field catalogue](https://proxymail.qa/docs/field-formats), its label, whether it’s required, and its test id. Build one in the app, or with your coding agent from what you describe or from a screenshot of your form, and save it to the project. Saving uses the [custom fields](https://proxymail.qa/docs/custom-fields) that already fill its fields and makes the ones it needs where nothing does, so `form_values` fills every field it safely can and leaves the rest for your test.

A project keeps up to 20 sign-up forms.

## Build one with your agent

Ask your agent to run the `build_signup_form_from_screenshot` prompt, then share a screenshot of each screen of your form. It reads the fields, shows you the spec as a table to correct, and saves it only once you say yes.

The screenshots stay with your agent: only the spec you agree to is sent to Proxy Mail QA.

You can also describe the form instead: “email, password, company size and the terms box, then a second screen with your role”.

## Build one in the app

Open **Project settings → Forms** and choose **New form**. Begin from a starter or a blank form, then:

- Add fields to each screen from the catalogue, change their labels, and mark them required or not
- Set a field’s options under its options button: the password’s length and the characters it needs, a minimum age, a country, or the choices a drop-down offers
- Add screens, each with its heading and page path
- See it under **Preview**, its code under **Code** and its tests under **Test**, each with Copy

Labels you leave empty follow the form’s language. Each field says how it’s filled: by Proxy Mail QA, by a ready-made custom field, or by your test. Once the form is saved, a field filled by a custom field names it, with **Open** to go to it in **Project settings → Custom fields**, and says when that custom field is off. A field that one of your [Standard fields](https://proxymail.qa/docs/custom-fields#turning-a-standard-field-off) switches turns off says so, with a button to them. A phone, ID or tax number field, a choice or the terms box is filled by a [ready-made field](https://proxymail.qa/docs/custom-fields#ready-made-fields): the one the form makes, by its test ID, or the project’s own for that kind of field. A phone field says when your test types it: the project’s Phone number puts in a number set aside for fiction in the UK, Australia, the US and Canada, or your app’s test number for another country, and leaves it empty for a country with neither.

In **Custom fields**, each custom field a form made has a **From** tag with the form’s name, which opens the form. One of your own that a form uses as it is has a **Used by** tag.

## Forms and your custom fields

A form describes your sign-up page: its screens, fields, labels and test ids, for its code, tests and preview. Custom fields decide what goes in a field on every fill, whether or not there’s a form. A form never needs a second custom field for the same field:

- **It uses what’s there.** Where one of your custom fields already fills a field, such as the project’s ready-made Phone number or your own rule for a company size question, saving uses it. It makes a ready-made one only where nothing fills the field.
- **It never beats yours silently.** If a ready-made field the form made wins over one of your own custom fields (say you added your own rule after saving the form), the form says so above its fields and at the field: **Keep yours** removes the form’s when you save; **Use the form’s** keeps the form’s and isn’t asked again. In **Custom fields**, your field has a **Clashes with** tag that opens the form at that field.
- **Saving tidies up.** When the form no longer uses a custom field it made, because you removed its field, changed its test id, or chose yours, saving asks first: move it to the new test id, remove it, or keep it. Where only leads change custom fields, a member asks the leads to remove it.

Your agent does the same with `save_signup_form`: the answer’s `fields_filled_by` says what fills each field, and `clashes` and `leftovers` wait for you to decide. Your agent asks you, then saves again with `choices` or `tidy`. Nothing is removed until then.

### A question your custom field answers

For a question of your own that one of your custom fields already answers, such as how many seats a team needs, add it from **Add a field → Your custom fields**. The form puts the field in its code, tests and preview; your custom field goes on deciding what goes in it on every fill. The field takes the custom field’s name and, where the custom field finds fields by test id, that test id; choose whether it’s a text box, a drop-down or a tick box. The field says whether your custom field finds it, and if a new label or test id means it doesn’t, what the custom field looks for.

Your agent adds one with section `custom`, the custom field’s id from `list_custom_fields`, a label and `options.type`; `finds` in `fields_filled_by` says whether the custom field finds it. A ready-made field isn’t added this way: use its field’s own section.

Have screenshots? **Copy prompt** gives a line to paste into your coding agent with them: your agent reads them, and they never come to Proxy Mail QA. **Open in** opens Qoder, Cursor, VS Code (1.140 or later) or Claude with the line already typed in: add your screenshots there, then send it. Nothing is sent until you do. If you connected Proxy Mail QA to this project from one of them, it gets a button of its own, such as **Open in Qoder**.

## Starters

Start from one of eight specs instead of a blank form. Your agent lists them with `list_signup_starters`, and **New form** in the app offers them.

| Starter     | What it asks for                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| b2c         | A consumer app: name, email, password, date of birth, the terms and an optional marketing box                            |
| b2b         | B2B SaaS: an account first, then the company’s name, website, role, team size, country, VAT and company number           |
| education   | A neutral age question (the date of birth, not “Are you over 13?”) and a parent’s email for younger learners             |
| marketplace | A seller’s account, then their business: type, country, address, date of birth, tax number and payout account            |
| travel      | The passenger details airlines send ahead (APIS), with a passport of Utopia, ICAO’s fictional state, and its expiry date |
| fintech     | What an identity check needs, for the US: legal name, date of birth, phone, address and a national ID number             |
| japan       | A Japanese form: family name first, the reading in katakana, then email, password, date of birth, phone and address      |
| china       | A Chinese form: phone first, then password, full name and the resident ID number for the real-name rule                  |

Each comes with notes, such as where Sign in with Google or LINE buttons go (they aren’t fields) and which values come from a payment provider’s test mode. Ask for one in another language or country, and its labels, drop-downs and ID formats follow. Nothing is saved until you save your version.

For a fintech form, pair the starter with KYC sandbox mode: `form_values` with `kyc_sandbox` gives a vendor’s own sandbox values (Stripe, Plaid, Onfido, Veriff, Didit, Cashfree or Setu) for a pass, a fail or a review, and the new address it makes takes the vendor’s names and date of birth. Proxy Mail QA never checks an identity: the values only match what each vendor’s sandbox expects. See [Field formats by country](https://proxymail.qa/docs/field-formats).

## What a spec holds

```json
{
  "name": "Main sign-up",
  "site": "https://staging.example.com/*",
  "language": "en",
  "screens": [
    {
      "path": "/signup",
      "fields": [
        { "section": "email" },
        { "section": "password", "options": { "min_length": 12, "classes": ["upper", "digit"] } },
        { "section": "business.team_size", "options": { "choices": ["1-10", "11-50", "51-200"] } },
        { "section": "consent.terms" }
      ]
    }
  ]
}
```

| Part     | What it says                                                                                        |
| -------- | --------------------------------------------------------------------------------------------------- |
| name     | What the form is called. Saving a form with the same name changes it                                |
| site     | The site it’s on, as the project lists it. Leave it out to match the form’s fields on every site    |
| language | The form’s language, for its default labels: en, de, fr, es, it, pt, nl, zh or ja                   |
| country  | A two-letter country code for the fields that depend on one: IDs, VAT numbers, phones and addresses |
| screens  | Up to 10 screens in order, each with an optional title, path and up to 30 fields; 60 fields in all  |
| A field  | Its section, required (true unless you say otherwise), label, testid and options; each section once |

A field’s label defaults to its section’s label in the form’s language, and its test id to `signup-` and the section id with dashes, such as `signup-business-team-size`.

A field with section `custom` names one of your custom fields instead, such as `{ "section": "custom", "custom_field": "<its id>", "label": "Seats", "options": { "type": "select", "choices": ["1-5", "6-20"] } }`. It needs a label, and its test id defaults to `signup-` and the label with dashes, such as `signup-seats`.

Options are only for the sections that take them: `min_length`, `max_length` and `classes` (`lower`, `upper`, `digit`, `symbol`) for a password, `min_age` for a date of birth, `country` for a country-dependent field, and `choices` for a drop-down or radio group.

## How each field is filled

`get_signup_form` and `GET /v1/project/signup-forms/{id}` say how each field gets its value:

| Fill          | Meaning                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------- |
| built\_in     | form\_values and Proxy Mail QA for Chrome fill it from the test person: names, email, password |
| custom\_field | A custom field fills it: a ready-made one, or for section custom the one the field names       |
| never         | Proxy Mail QA leaves it for your test                                                          |

Only the `custom_field` sections get a custom field, a ready-made one: phone, ID and tax numbers, gender, language, how someone heard about you, role, team size, business type and the terms box. A form uses the project’s own ready-made ones where it has them, such as the ID and tax number fields a lead adds in **Project settings → Custom fields**, or all five at once with `update_project`’s `fill_id_fields`. Each one a form makes finds its field by the test id, so add those `data-testid` attributes to your form. Removing a form keeps its custom fields unless you ask for them to go too: in the app, **Also remove the custom fields it made** is ticked in the Remove dialog; agents and the API send `remove_custom_fields`. A custom field another form still uses stays. Where only leads change custom fields, a member’s removal asks the leads to remove them instead (**Also ask the leads to remove the custom fields it made**), one request for each, which they answer in **Project settings → Custom fields**. Otherwise, a custom field someone else added stays.

## Get it as code

Your agent can turn a saved form into code for your app with `get_signup_form_code`, in one of three kinds:

| Format          | What you get                                                      |
| --------------- | ----------------------------------------------------------------- |
| react-hook-form | A React component with react-hook-form and a zod schema (default) |
| react           | A React component with plain state and no other packages          |
| html            | One HTML page with its own script                                 |

Each field checks what the spec asks for: the password’s rules, the age on a date of birth, and an ID or VAT number’s format and check digit for its country. Messages and buttons are in the form’s language. Screens show one after another, with Next and Back. Every field keeps its `data-testid`, so the form’s custom fields find it.

The ID checks run in the browser to help people as they type. Check them on your server too.

Your agent fits the code to your app: your components and styles, with the test ids and rules kept. The answer’s `notes` say what to look at, such as a drop-down still offering our usual answers.

## Get tests for it

`get_signup_form_test` gives tests for a saved form, for Playwright (the default) or Cypress. Each field gets values the form should take and values it should refuse, one at a time, with every other field filled in properly:

- Left empty, when the field is required
- An email address with no @, or no dot after it
- A password a character too short, and one without each kind of character the spec asks for
- A date of birth for someone who turns the minimum age tomorrow, and one for someone who turned it today
- An ID or VAT number with the wrong check digit, a character short or a letter where a digit goes
- Names with accents and apostrophes, and phone numbers written in other ways, which the form should take

The tests make one test address with a persona and a password before they start, and delete it after. They find each field by the `data-testid` the code export writes, and expect a refusal to show as the field’s `<test id>-error` message or `aria-invalid="true"`. Set `SIGNUP_URL` to the form’s page. If your form wasn’t made from the code export, check its test ids and error messages match, or change the test’s helpers.

A field where Proxy Mail QA gives no value, such as a VAT number, is named in `notes`: put a value your form takes in the test’s `valid()`.

## On a locked project

Where only leads change custom fields, a member’s save, in the app or by their agent, goes to the leads as one request for the whole form. In the app the button says **Ask the leads**. The form waits as a draft, which can still be read and changed. A lead approves or declines it in **Project settings → Custom fields**; approving saves the form and makes its custom fields together.

## In the API

| Where                                          | What                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [MCP](https://proxymail.qa/docs/mcp)           | list\_signup\_starters, list\_signup\_forms, get\_signup\_form, save\_signup\_form, delete\_signup\_form, get\_signup\_form\_code, get\_signup\_form\_test                                                                                                                                 |
| [REST API](https://proxymail.qa/docs/rest-api) | GET /v1/signup-starters, GET and POST /v1/project/signup-forms, GET and DELETE /v1/project/signup-forms/{id}, GET /v1/project/signup-forms/{id}/code and /test                                                                                                                             |
| [npm](https://proxymail.qa/docs/node)          | signupStarters({ id?, language?, country? }), signupForms(), signupForm(id), saveSignupForm(spec, id?), deleteSignupForm(id, { removeCustomFields? }), signupFormCode(id, { format?, requested? }), signupFormTest(id, { framework? })                                                     |
| [Python](https://proxymail.qa/docs/python)     | list\_signup\_starters(starter\_id=None), list\_signup\_forms(), get\_signup\_form(form\_id), save\_signup\_form(spec, form\_id=None), delete\_signup\_form(form\_id, remove\_custom\_fields=False), signup\_form\_code(form\_id, format=...), signup\_form\_test(form\_id, framework=...) |

[Previous](https://proxymail.qa/docs/custom-fields.html): Custom fields

[Next](https://proxymail.qa/docs/limits.html): Limits and safety
