Skip to main content
GET
List contact fields (public API)
Lists every field your contacts can carry, and what each one expects.

Overview

A contact field is a typed, named slot on a contact — order_number, lead_source, renewal_date. Two things make a field different from a note you keep on your own side:
  1. An agent can speak it. {{contact.order_number}} in an agent’s prompt is replaced with this contact’s value at the moment the call is placed.
  2. The platform validates it. A field declared number rejects "twelve" on the way in, rather than surfacing as a confused agent mid-call.
Read this endpoint first. It tells you which keys PATCH /contacts/{id} will accept and how each value must be shaped.
The catalog is thirty-six fields, not eleven. InstaView seeds a default set covering identity, the contact’s employer, orders and invoices, the relationship, appointments and screening — so most of what you would have defined by hand already exists, with CSV aliases attached. If you built a form or a table that renders every field it gets back, expect thirty-six rows rather than a handful, and read category if you want them grouped the way the dashboard groups them.

What you get back

Two kinds of field, merged into one list: A seeded field is the platform’s contract with the prompt compiler and the CSV importer, so one company editing it directly would change what its token means for everybody. To change a seeded field’s label or type for your company alone, define your own field with the same key: it shadows the seeded one, and comes back with isCompanyOverride: true.
Eight keys are RESERVED and cannot be shadowed at all: first_name, last_name, email, phone, company_name, company_description, agent_name and profile. A POST /contact-fields on one of those is refused — the platform resolves them itself, so a company definition would be advertised in the palette and then ignored on the call.isSystem: true alone does not tell you which is which, because most seeded keys (order_number, is_vip, lead_source) can be shadowed. Check writable if what you need to know is whether you can send a value for a key.

Reading the flags

One of string, number, date, bool, enum or tags. A write is checked against it: a number field takes 42 or "42" but not "twelve"; a bool field takes true, "true", "yes" or "1" and their negatives, but not "maybe"; a date field is stored as an ISO timestamp; an enum field takes only a value from its own enumOptions.A tags field stores a string[] and is the one type that accepts two shapes: an array, or a comma-separated string, so one CSV cell holding several tags maps onto one field. See Set Contact Fields for what it trims, de-duplicates and treats as an erase.
One of identity, organisation, commercial, relationship, scheduling, recruiting, platform or custom. It is the grouping the dashboard’s variable palette uses, and the first key this list is ordered by — so iterating the response and breaking on a change of category gives you the same panels a user sees.Set by InstaView and not writable. A field you define is always custom; a field of yours that shadows a seeded one reports the seeded field’s category, so job_title stays under organisation for everybody even after you relabel it.
A PII field is masked in logs and is excluded from everything an agent gets: it is neither in the prompt nor in the document the agent can query. That is what keeps email and phone off every call without anyone deciding, and it is enforced rather than defaulted.Two things get past it. inEssentialPromptSet below, which is ours — first_name is personal data and is also the first word of the call. And allowPiiInContext, which is yours: set it on the one field an agent has to be able to say, and the value joins both the document and the prompt. For a collections agent the amount owed is the entire reason for the call. Setting it on a field that is not isPii is a 400, not a no-op.
Your decision that this particular personal datum belongs on a call. Writable, and only meaningful on an isPii field. See Create Contact Field.
Read-only, and ours to decide. A short set of fields goes into the prompt of every context-enabled agent, because a prompt line is always known while a document entry is known only if the agent thinks to look. Everything else a contact has a value for reaches the agent through the generated contact document instead, which costs nothing until it is queried.Both halves are gated by contextConfig.useContactContext on the agent. There is no per-field opt-in to maintain: define fields, store values, and an agent with the switch on can use them.
A handful of fields exist so an author can use the token, but resolve from somewhere other than the contact: company_description is your company’s own blurb, agent_name is the agent’s. Sending a value for one is a 422 naming the key. They are listed here because an agent author still needs to see them.
The flag to branch on before a write, and not the same thing as !readOnly. Look at first_name in the response above: readOnly is false, and a value for it is still refused with a 422. It is one of the keys the platform RESERVES — the identity fields (first_name, last_name, email, phone) plus company_name, company_description, agent_name and profile. Those four identity fields are writable, just as properties of the contact itself rather than as fields.So readOnly answers “where does this value come from” and writable answers “will this endpoint take one from me”. writable: false always means do not send a value for this key; it covers every readOnly field as well as every reserved one.
Header names an import should also match this field on, beyond the key and label — so a sheet whose column is called Order # can be recognised as order_number rather than mapped by hand.Every writable seeded field arrives with aliases in English, Slovak and Czech — renewal_date carries renewal, renews, dátum obnovenia and more — ready for the importer to match on. Adding your own with PATCH /contact-fields/{id} does not touch InstaView’s. Read the warning below first: nothing consumes any of them yet.
Declared, but nothing consumes it yet. The current CSV importer maps against a fixed list of built-in contact properties and does not read this array, so setting csvAliases today changes no import behaviour. It is stored so the catalog is complete before the contact-field import lands. Until then, map these columns explicitly.
id exists only to address PATCH and DELETE. Everywhere else — a prompt token, a values payload, a CSV mapping — a field is addressed by key.

Ordering and paging

Ordered by category first — in the fixed order identity, organisation, commercial, relationship, scheduling, recruiting, platform, custom — then by displayOrder, then by key. displayOrder therefore only ever separates fields within one category, which is why each category’s own numbering restarts rather than continuing one long sequence. Unpaginated: your whole catalog is smaller than one page of any other list endpoint, so there is nothing to page through.

Scopes

read:contacts (or its read:candidates alias). Changing the catalog needs write:contacts. Nothing to rotate: any key that can already read your contacts can read their field catalog.

Create Contact Field

Define a field of your own

Update Contact

Store values against a contact

Get Contact

Read one contact’s values

Update Contact Field

Change one of your own fields

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Response

200 - application/json
data
object[]
required

Every field this company can use, ordered by displayOrder then key

total
number
required

Number of fields in the catalog

Example:

12