List custom fields

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 organizationThis endpoint
OWNERAllowed
ADMINAllowed
MEMBERAllowed
A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

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

FieldTypeDescription
successbooleanIndicates if the operation was successful
dataarrayThe custom fields
data[].idstringUnique identifier — the customFieldId of the rename and delete calls
data[].keystringThe key values are written under, unique in the organization. Never changes
data[].labelstringThe name people read
data[].typestringtext, number, date or boolean (yes/no). Never changes
data[].createdAtstringISO creation date
data[].updatedAtstringISO 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.