# Custom Fields API



> Custom fields define the typed workspace schema shared by subscribers, forms, and segments. This guide explains how to choose field types, map external data, create definitions, and avoid breaking forms or reports with unsafe schema changes.



- Human page: https://mailrith.com/developers/custom-fields

- Category: API Resources

- Reading time: 6 min read



## What this guide covers

Manage typed subscriber fields before syncing values, forms, segments, or migrated data.



## Manage the Workspace Field Schema

Custom fields are the structured pieces of information a workspace stores about subscribers. Examples include plan, company, location, signup source, renewal date, lead score, or account owner.

Unlike tags, custom fields have a type. That type helps Mailrith forms, subscriber profiles, and segments understand how to display, collect, and compare the value.

Create or map custom fields before writing subscriber values into them. This prevents migrations from scattering important data into the wrong field or losing useful type information.

1. List existing custom fields with `GET /v1/custom-fields`.
2. Map external fields to existing Mailrith field IDs when the meaning matches.
3. Create new custom fields before importing subscriber values that need a typed field.
4. Use controlled choices for plan, region, lifecycle stage, or other values where spelling must stay consistent.
5. Write subscriber field values only after the field definition exists.
6. Ask a Mailrith user to review the field in [Custom Fields](https://mailrith.com/docs/custom-fields.md), [Forms](https://mailrith.com/docs/forms.md), and [Segments](https://mailrith.com/docs/segments.md) before relying on it in live targeting.

- Use text fields for free-form values such as company name.
- Use select fields when the allowed answers need to be controlled, such as plan or region.
- Use date or number fields when the value needs date or numeric comparisons in segments.
- Keep labels plain and user-friendly because workspace users will see them in the app.
- Avoid deleting fields until you understand which forms, segments, imports, or subscriber records depend on them.

## Endpoint Overview

`GET /v1/custom-fields` lists the workspace schema. Use it to map external field names to Mailrith field IDs before a sync or migration.

`POST /v1/custom-fields` creates a new field definition. Item endpoints let you inspect, update, or delete one field when your integration owns that schema.

Be careful with updates. Renaming a field is usually safe when users understand the new label. Changing the meaning or type of a field can confuse forms, segments, and reports that already use it.

Related OpenAPI operation groups:
- Custom Fields

**List Custom Fields**

```bash
curl "https://api.mailrith.com/v1/custom-fields?limit=50" \
  -H "Authorization: Bearer mrk_example_secret_key"
```

**Create a Custom Field**

```bash
curl -X POST https://api.mailrith.com/v1/custom-fields \
  -H "Authorization: Bearer mrk_example_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Plan",
    "type": "Single Select",
    "settings": {
      "options": ["Free", "Pro", "Enterprise"]
    }
  }'
```



## Related Guides

- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the core subscriber write surface in `v1`. This guide explains when to list, when to upsert, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests.

- [Forms API](https://mailrith.com/developers/forms.md): The forms surface lets integrations manage capture points outside the app. This guide explains when to list, create, update, or delete forms, how forms depend on fields and tags, and how to change live forms without breaking website signups.

- [Segments API](https://mailrith.com/developers/segments.md): The segments surface supports saved subscriber definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save them, and why preview is the safest step before using complex subscriber rules.