# 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 sources, create field definitions, and avoid schema changes that break forms or reports.



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

- Markdown page: https://mailrith.com/developers/custom-fields.md

- Category: API Resources

- Reading time: 6 min read

- Last updated: 2026-07-13

- Related keywords: Custom Fields API, Custom Fields API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Manage the Workspace Field Schema, Endpoint Overview, Subscribers API, Forms API, Segments API



## AI Agent Notes

- Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document.

- Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise.

- Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using.



## What this guide covers

Manage typed subscriber fields before you sync field values, forms, segments, or migrated subscriber data.



## Manage the Workspace Field Schema

Custom fields are structured fields that a workspace stores on subscriber records. Examples include plan, company, location, signup source, renewal date, lead score, and account owner.

Custom fields are different from tags because each custom field has a type. The type tells Mailrith forms, subscriber profiles, and segments how to display, collect, and compare the field value.

Create or map custom fields before you write subscriber values to those fields. This order helps prevent migrations from writing important subscriber data to the wrong field or losing useful type information.

1. List existing custom fields with `GET /v1/custom-fields`.
2. Map each external field to an existing Mailrith field ID when both fields have the same meaning.
3. Create new custom fields before you import subscriber values that require a typed field.
4. Use controlled choices for plan, region, lifecycle stage, or any other field 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). The field is ready for live targeting when the label, type, choices, and usage match the intended subscriber data.

- Use text fields for free-form values, such as company name.
- Use select fields when subscribers or users must choose from controlled answers, such as plan or region.
- Use date or number fields when segments need to compare dates or numbers.
- Keep labels plain and user-friendly because workspace users see those labels in the app.
- Do not delete fields until you know which forms, segments, imports, or subscriber records depend on those fields.

## Endpoint Overview

`GET /v1/custom-fields` lists the workspace schema. Use the API response to map external field names to Mailrith field IDs before you start 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.

Use care when you update custom fields. Renaming a field is usually safe when users understand the new label. Changing a field meaning or type can confuse forms, segments, and reports that already use the field.

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 main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, 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 API lets integrations manage capture forms outside the app. This guide explains when to list, create, update, or delete forms, how forms depend on fields and tags, and how to update live forms without breaking website signups.

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