Custom Fields

Organizations define their own extra fields for sales, contacts, and companies. Use this endpoint to discover which fields exist, which generated keys to use, and what values they accept before sending custom_fields on a create request.

Get custom fields

GET /api/v2/organizations/{organization_id}/custom-fields

Returns the field definitions for each entity that supports custom fields, keyed by API entity name: sales, contacts, and companies.

Get custom fields request

curl https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/custom-fields \
  -H "X-API-KEY: your-api-key"

Example response

{
  "sales": [
    {
      "key": "notes",
      "label": "Notes",
      "type": "string",
      "ui_type": "paragraph"
    },
    {
      "key": "tier",
      "label": "Tier",
      "type": "enum",
      "options": ["Gold", "Silver"],
      "default": "Silver"
    },
    {
      "key": "deal_size",
      "label": "Deal Size",
      "type": "number"
    }
  ],
  "contacts": [
    {
      "key": "notes",
      "label": "Notes",
      "type": "string",
      "ui_type": "paragraph"
    }
  ],
  "companies": [
    {
      "key": "notes",
      "label": "Notes",
      "type": "string",
      "ui_type": "paragraph"
    }
  ]
}

Field definition properties

Each field definition includes the attributes below. Additional attributes may appear as the API evolves — ignore any attribute that is not documented here.

Name
key
Description
The generated field key to use in custom_fields payloads. HyperRep creates this from the admin label by lowercasing it, replacing non-alphanumeric groups with underscores, trimming edge underscores, and appending a number when needed for uniqueness.
Name
label
Description
Human-readable field label configured in the HyperRep admin UI.
Name
type
Description
Expected value type: string, number, boolean, or enum.
Name
ui_type
Description
Optional presentation hint: text, number, boolean, enum, date, address, or paragraph. address fields take free-form string values. date fields take a date-only string in YYYY-MM-DD format.
Name
options
Description
Allowed values for enum fields. HyperRep normalizes stored enum or options configuration into this response property.
Name
default
Description
Default value applied to newly created records when the field is not provided.

Validation rules

custom_fields values sent to POST /sales, POST /contacts, and POST /companies are validated against these definitions:

Unknown field keys are rejected.
string fields require JSON strings, number fields require JSON numbers, and boolean fields require JSON booleans.
enum fields require one of the configured options.
Fields with the date presentation take a string in YYYY-MM-DD format — zero-padded, and it must be a real calendar date. Example: 2026-07-09.
null is accepted for any field and leaves it blank.

Validation failures return a 400 whose detail names the offending field, for example Custom field "tier" must be one of: Gold, Silver.