GET /api/v1/custom-fields
Every custom field of the organization. Read it before writing customFields on a contact: only
the keys listed here are accepted.
The list is complete: there is no pagination and no search on it — an organization has at most 50
fields.
Authorization
| Role in the organization | This endpoint |
|---|---|
OWNER | Allowed |
ADMIN | Allowed |
MEMBER | Allowed |
Example
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
"https://www.agentsmail.io/api/v1/custom-fields"Response
200 OK— the custom fields, oldest first. An organization with none answers an empty array.401 Unauthorized— missing or invalid key, or its owner left the organization.429 Too Many Requests— over 120 requests in a minute for this key.
Response fields
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the operation was successful |
data | array | The custom fields |
data[].id | string | Unique identifier — the customFieldId of the rename and delete calls |
data[].key | string | The key values are written under, unique in the organization. Never changes |
data[].label | string | The name people read |
data[].type | string | text, number, date or boolean (yes/no). Never changes |
data[].createdAt | string | ISO creation date |
data[].updatedAt | string | ISO date of the last change |
Example response
json
{
"success": true,
"data": [
{
"id": "4f1a9c2e",
"key": "utm_source",
"label": "UTM source",
"type": "text",
"createdAt": "2026-11-02T08:11:00.000Z",
"updatedAt": "2026-11-02T08:11:00.000Z"
}
]
}Notes
- No
?search=and no pagination here. The whole list comes back in one call — look a key up on your side.