--- title: Fields and relationships | Lightfield description: Learn how fields, relationships, and their value types work in the Lightfield API. --- Fields and relationships are the core data model for CRM objects in Lightfield. **Fields** store data on an object (e.g. a name, email, or deal value), while **relationships** link objects together (e.g. an opportunity’s account or contacts). When creating or updating objects via the API (or through the SDKs), you pass field values in the `fields` object. Each key in that object corresponds to a field on the object type. ## Field keys Field and relationship keys use a `$` prefix to distinguish system-defined entries from custom ones: - **System fields and relationships**: Prefixed with `$`, e.g. `$name`, `$stage`, `$account`. - **Custom fields and relationships**: No prefix, e.g. `priority`, `partners`. ``` { "fields": { "$name": { "valueType": "TEXT", "value": "Acme Corp" }, "$stage": { "valueType": "SINGLE_SELECT", "value": "opt_..." }, "priority": { "valueType": "NUMBER", "value": 1 } } } ``` ## Discovering definitions Use the definitions endpoint to discover all fields and relationships available on an object type: ``` GET /v1/{objectType}/definitions ``` For example: Terminal window ``` curl https://api.lightfield.app/v1/opportunities/definitions \ -H "Authorization: Bearer $API_KEY" \ -H "Lightfield-Version: 2026-03-01" ``` The response includes the full schema for both fields and relationships: ``` { "objectType": "opportunity", "fieldDefinitions": { "$name": { "id": "ad_...", "slug": "name", "label": "Name", "description": null, "valueType": "TEXT", "system": true, "typeConfiguration": {} }, "$stage": { "id": "ad_...", "slug": "stage", "label": "Stage", "description": "What stage is the opportunity in?", "valueType": "SINGLE_SELECT", "system": true, "typeConfiguration": { "options": [ { "id": "opt_...", "label": "Prospecting", "description": null }, { "id": "opt_...", "label": "Closed Won", "description": null } ] } } }, "relationshipDefinitions": { "$account": { "id": null, "slug": "account", "label": "Account", "description": null, "system": true, "cardinality": "HAS_ONE", "objectType": "account" } } } ``` This is especially useful for resolving select option IDs to their labels, and for discovering which keys will appear in record responses. ### Supported object types | Object type | Path | | ------------- | ------------------------------- | | Accounts | `/v1/accounts/definitions` | | Contacts | `/v1/contacts/definitions` | | Opportunities | `/v1/opportunities/definitions` | ### Field definition object | Property | Type | Description | | ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | | `id` | `string \| null` | Unique identifier (prefixed with `ad_`), or `null` for synthesized fields. | | `slug` | `string` | Internal slug for the field. | | `label` | `string` | Human-readable label. | | `description` | `string \| null` | Optional description. | | `valueType` | `string` | The field’s value type. See [field value types](#field-value-types). | | `system` | `boolean` | `true` for built-in fields, `false` for custom fields. | | `readOnly` | `boolean` | Present and `true` for fields that are not writable via the API (e.g. AI-generated summaries). Absent on writable fields. | | `typeConfiguration` | `object` | Type-specific configuration. See [type configuration](#type-configuration). | ### Relationship definition object | Property | Type | Description | | ------------- | ---------------- | --------------------------------------------------------------------------------- | | `id` | `string \| null` | Unique identifier (prefixed with `rd_`), or `null` for synthesized relationships. | | `slug` | `string` | Internal slug for the relationship. | | `label` | `string` | Human-readable label. | | `description` | `string \| null` | Optional description. | | `system` | `boolean` | `true` for built-in relationships, `false` for custom relationships. | | `cardinality` | `string` | `HAS_ONE` or `HAS_MANY`. | | `objectType` | `string` | The related object type (e.g. `account`, `contact`, `user`). | ## Field value types Every field has a `valueType` that determines the shape of its value: | Type | Value format | Description | | ------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | `TEXT` | `string` | Plain text. | | `NUMBER` | `number` | A number with up to 2 decimal places, within safe integer range. | | `CHECKBOX` | `boolean \| null` | A true/false value. | | `CURRENCY` | `number \| null` | A numeric amount. The currency code (e.g. `USD`) is set in the field’s type configuration. | | `DATETIME` | `string \| null` | An ISO 8601 datetime string with timezone offset (e.g. `"2026-03-16T12:00:00+00:00"`). Stored as UTC. | | `EMAIL` | `string[]` | An array of email addresses (RFC 5322). | | `TELEPHONE` | `string[]` | An array of phone numbers. See [telephone format](#telephone-format) below. | | `URL` | `string \| string[] \| null` | A URL or array of URLs. | | `ADDRESS` | `object` | A structured address object. See [address format](#address-format) below. | | `FULL_NAME` | `object` | An object with `firstName` and `lastName` properties. | | `SOCIAL_HANDLE` | `string \| null` | A social media handle or profile URL. See [social handle format](#social-handle-format) below. | | `SINGLE_SELECT` | `string \| null` | The `id` of a select option (prefixed with `opt_`). | | `MULTI_SELECT` | `string[]` | An array of select option `id`s. | | `READONLY_MARKDOWN` | `string` | Read-only markdown content, typically AI-generated. Not writable via the API. | Fields with array values (`EMAIL`, `TELEPHONE`, `MULTI_SELECT`) support multiple values. Fields like `SINGLE_SELECT`, `CHECKBOX`, and `NUMBER` accept a single value or `null`. ## Address format Address values are objects with the following properties, all optional: | Property | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------------------ | | `street` | `string` | Street address line 1. | | `street2` | `string` | Street address line 2 (apartment, suite, etc.). | | `city` | `string` | City name. | | `state` | `string` | State or region. | | `postalCode` | `string` | Postal or ZIP code. | | `country` | `string` | ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`). Must be exactly 2 characters. | | `latitude` | `number` | Latitude coordinate. | | `longitude` | `number` | Longitude coordinate. | ``` { "street": "123 Main St", "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "US" } ``` ## Telephone format Phone numbers are validated and normalized on input: - **With `+` prefix**: Validated as an international number in E.164 format (e.g. `"+12025551234"`). - **Without `+` prefix**: Validated as a US number first, then falls back to accepting 7–15 digit local numbers. - **Extensions**: Supported via `;ext=` notation (e.g. `"+12025551234;ext=100"`). Various input formats like `x100`, `ext:100`, and `#100` are automatically normalized to the `;ext=` format. ``` ["+12025551234", "+442071234567;ext=100"] ``` ## Social handle format `SOCIAL_HANDLE` fields store a social media profile URL. Each social handle field has a `handleService` in its type configuration that specifies the platform: `TWITTER`, `LINKEDIN`, `FACEBOOK`, or `INSTAGRAM`. Values must be a valid profile URL for the configured platform: | Platform | Accepted URL formats | | ----------- | ----------------------------------------------------------------------- | | `TWITTER` | `https://twitter.com/{username}`, `https://x.com/{username}` | | `LINKEDIN` | `https://linkedin.com/in/{slug}`, `https://linkedin.com/company/{slug}` | | `FACEBOOK` | `https://facebook.com/{username}`, `https://fb.com/{username}` | | `INSTAGRAM` | `https://www.instagram.com/{username}` | Regional subdomains (e.g. `https://uk.linkedin.com/in/...`) and query parameters are accepted. ``` "https://x.com/lightfield" "https://www.linkedin.com/in/jane-doe" "https://www.instagram.com/lightfield" ``` Pass `null` to clear a social handle field. ## Select options `SINGLE_SELECT` and `MULTI_SELECT` fields reference predefined options by their `id`. Use the [definitions endpoint](#discovering-definitions) to discover the available options for a field. Each option has the following shape: | Property | Type | Description | | ------------- | ---------------- | ---------------------------------------- | | `id` | `string` | Unique identifier, prefixed with `opt_`. | | `label` | `string` | Display label. | | `description` | `string \| null` | Optional description. | When setting a `SINGLE_SELECT` value, pass the option’s `id` as a string. For `MULTI_SELECT`, pass an array of option `id`s. ``` { "fields": { "$stage": "opt_abc123", "tags": ["opt_def456", "opt_ghi789"] } } ``` Select options are org-specific. Always read them from the definitions endpoint rather than hardcoding option IDs. ## Type configuration Some field types include additional configuration via `typeConfiguration` on the field definition. You can read these from the [definitions endpoint](#discovering-definitions). | Type | Configuration | Description | | --------------- | -------------------------- | -------------------------------------------------------------------------------------- | | `CURRENCY` | `currency` | ISO 4217 currency code (e.g. `"USD"`). | | `EMAIL` | `unique`, `multipleValues` | Whether values must be unique across objects, and whether multiple emails are allowed. | | `TELEPHONE` | `unique`, `multipleValues` | Same as email — uniqueness and multiple value support. | | `URL` | `unique`, `multipleValues` | Same as email — uniqueness and multiple value support. | | `SOCIAL_HANDLE` | `handleService` | Platform hint: `TWITTER`, `LINKEDIN`, `FACEBOOK`, or `INSTAGRAM`. | | `SINGLE_SELECT` | `options` | The list of available select options. | | `MULTI_SELECT` | `options` | The list of available select options. | Types not listed above (such as `TEXT`, `NUMBER`, `DATETIME`, `CHECKBOX`, `ADDRESS`, `FULL_NAME`, and `READONLY_MARKDOWN`) return an empty `typeConfiguration: {}`. ## System vs custom fields Fields and relationships can be either **system** or **custom**: - **System** entries are built-in, prefixed with `$`, and cannot be deleted. They are present on every object of their entity type (e.g. `$name` on accounts, `$account` on opportunities). - **Custom** entries are user-defined and can be created, updated, and removed through the API or the Lightfield UI. Both system and custom entries follow the same value type rules described above. ## ID prefixes Lightfield uses prefixed IDs to distinguish between entity types: | Entity | Prefix | Example | | ----------------------- | ------ | ------------ | | Account | `acc_` | `acc_abc123` | | Contact | `con_` | `con_abc123` | | Opportunity | `opp_` | `opp_abc123` | | Member | `mem_` | `mem_abc123` | | Field definition | `ad_` | `ad_abc123` | | Relationship definition | `rd_` | `rd_abc123` | | Select option | `opt_` | `opt_abc123` | | Attribute value | `av_` | `av_abc123` | | Relationship value | `rv_` | `rv_abc123` |