Reference
Field reference
Every Leads data point the Zoye API carries. Standard fields can be written by any key. Privileged fields can only be written by a secret key - a publishable key's attempt is ignored and returned in ignoredFields.
Standard fields
Writable by any key type, publishable or secret. These cover the everyday contact data a signup form collects. At least one of email, phone, or name is required on every contact.
| Field | Type | Applies to | Notes |
|---|---|---|---|
| name | string | Person + Company | Full name (person) or company name. |
| string | Person + Company | Primary email. One of email / phone / name is required. | |
| phone | string | Person + Company | Primary phone number. |
| company | string | Person | The company a person belongs to. |
| position | string | Person | Job title or role. |
| type | "person" | "company" | Person + Company | Defaults to person. |
| source | string | Person + Company | Where the lead came from, e.g. website-form. |
| notes | string | Person + Company | Free-text notes. |
| address | string | Person + Company | Street address. |
| city | string | Person + Company | City. |
| country | string | Person + Company | Country. |
| website | string | Person + Company | Website URL. |
| string | Person + Company | LinkedIn profile URL. | |
| string | Person + Company | Twitter / X handle or URL. | |
| lastContactedDate | ISO 8601 date | Person + Company | When the contact was last reached. |
| customFields | object { label: value } | Person + Company | Maps to your workspace custom fields by label. |
| externalId | string | Person + Company | Your own id for the contact, for dedupe / sync. |
| metadata | object | Person + Company | Arbitrary key / value data stored with the contact. |
Privileged fields
Writable by a secret key only. These control routing, ownership, and relationships inside Zoye, so they are blocked for browser-safe publishable keys.
| Field | Type | Applies to | Notes |
|---|---|---|---|
| lifecycleStage | string | Person + Company | Pipeline lifecycle stage. |
| tags | string[] | Person + Company | Labels applied to the contact. |
| status | string | Person + Company | Stage / status value. |
| assigneeId | string | Person + Company | User id of the primary owner. |
| assignedUserIds | string[] | Person + Company | User ids assigned to the contact. |
| watchingUserIds | string[] | Person + Company | User ids watching the contact. |
| linkedContactIds | string[] | Company | Member contacts linked to a company. |
| linkedNoteIds | string[] | Person + Company | Notes linked to the contact. |
What happens with a publishable key
When a publishable key includes a privileged field, the contact is still created from its standard fields, and each blocked field name is returned in the ignoredFields array of the response so you know exactly what was dropped.
Custom fields
Anything that is not a built-in field can go in customFields as a { label: value } object. Labels are matched against your workspace custom fields; any that do not match are returned in unresolvedCustomFields. See the REST API reference for the response shape.