# List ## Create a list **post** `/v1/lists` Creates a new list. The `$name` and `$objectType` fields are required. Supports idempotency via the `Idempotency-Key` header. **[Required scope](/using-the-api/scopes/):** `lists:create` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Body Parameters - `fields: object { "$name", "$objectType", "$description", "$kind" }` Field values for the new list. Required: `$name` (string) and `$objectType`. - `"$name": string` Display name of the list. - `"$objectType": string` The type of entities this list contains. Use `$account`, `$contact`, or `$opportunity` (the `$` prefix identifies system types). Bare slugs without the prefix (e.g. `account`) are accepted for backward compatibility but are deprecated. - `"$description": optional string` Optional description of what this list is for. - `"$kind": optional "target"` Product-level list purpose. Normally omit to create a regular list; reserve `target` for the single account-prioritization (APG) demand list per org, and only for account/contact lists. - `"target"` - `relationships: optional object { "$accounts", "$contacts", "$opportunities" }` Relationships to set on the new list. - `"$accounts": optional string or array of string` Account ID(s) to add as initial members. List `$objectType` must be `account`. - `string` - `array of string` - `"$contacts": optional string or array of string` Contact ID(s) to add as initial members. List `$objectType` must be `contact`. - `string` - `array of string` - `"$opportunities": optional string or array of string` Opportunity ID(s) to add as initial members. List `$objectType` must be `opportunity`. - `string` - `array of string` ### Returns - `ListCreateResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. ### Example ```http curl https://api.lightfield.app/v1/lists \ -H 'Content-Type: application/json' \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "fields": { "$name": "$name", "$objectType": "$objectType" } }' ``` #### Response ```json { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink" } ``` ## Update a list **post** `/v1/lists/{id}` Updates an existing list by ID. Only included fields are modified. Supports idempotency via the `Idempotency-Key` header. **[Required scope](/using-the-api/scopes/):** `lists:update` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Path Parameters - `id: string` Unique identifier of the list to update. ### Body Parameters - `fields: optional object { "$description", "$kind", "$name" }` Field values to update — only provided fields are modified; omitted fields are left unchanged. - `"$description": optional string` Optional description of what this list is for. Pass null to clear. - `"$kind": optional "target"` Product-level list purpose. Normally leave unset; reserve `target` for the single account-prioritization (APG) demand list per org (account/contact lists only). Pass null to clear. - `"target"` - `"$name": optional string` Display name of the list. - `relationships: optional object { "$accounts", "$contacts", "$opportunities" }` Relationship operations. Use the key matching the list's `$objectType` (e.g. `$accounts` for an account list). - `"$accounts": optional object { add, remove }` Add/remove accounts. List `$objectType` must be `account`. - `add: optional string or array of string` Entity ID(s) to add to the list. - `string` - `array of string` - `remove: optional string or array of string` Entity ID(s) to remove from the list. - `string` - `array of string` - `"$contacts": optional object { add, remove }` Add/remove contacts. List `$objectType` must be `contact`. - `add: optional string or array of string` Entity ID(s) to add to the list. - `string` - `array of string` - `remove: optional string or array of string` Entity ID(s) to remove from the list. - `string` - `array of string` - `"$opportunities": optional object { add, remove }` Add/remove opportunities. List `$objectType` must be `opportunity`. - `add: optional string or array of string` Entity ID(s) to add to the list. - `string` - `array of string` - `remove: optional string or array of string` Entity ID(s) to remove from the list. - `string` - `array of string` ### Returns - `ListUpdateResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. ### Example ```http curl https://api.lightfield.app/v1/lists/$ID \ -H 'Content-Type: application/json' \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" \ -d '{}' ``` #### Response ```json { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink" } ``` ## Retrieve a list **get** `/v1/lists/{id}` Retrieves a single list by its ID. **[Required scope](/using-the-api/scopes/):** `lists:read` **[Rate limit category](/using-the-api/rate-limits/):** Read ### Path Parameters - `id: string` Unique identifier of the list to retrieve. ### Returns - `ListRetrieveResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. ### Example ```http curl https://api.lightfield.app/v1/lists/$ID \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink" } ``` ## List lists **get** `/v1/lists` Returns a paginated list of lists. Results are sorted by when the record was created in Lightfield (`createdAt`), newest first. Use `offset` and `limit` to paginate through results. See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination. **[Required scope](/using-the-api/scopes/):** `lists:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Query Parameters - `limit: optional number` Maximum number of records to return. Defaults to 25, maximum 25. - `offset: optional number` Number of records to skip for pagination. Defaults to 0. ### Returns - `ListListResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, httpLink }` Array of list objects for the current page. - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of lists matching the query. ### Example ```http curl https://api.lightfield.app/v1/lists \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink" } ], "object": "object", "totalCount": 0 } ``` ## List accounts in a list **get** `/v1/lists/{listId}/accounts` Returns a paginated list of accounts that belong to the specified list. Results are sorted by when the record was created in Lightfield (`createdAt`), newest first. **[Required scopes](/using-the-api/scopes/):** `lists:read` and `accounts:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Path Parameters - `listId: string` Unique identifier of the list. ### Query Parameters - `limit: optional number` Maximum number of records to return. Defaults to 25, maximum 25. - `offset: optional number` Number of records to skip for pagination. Defaults to 0. ### Returns - `ListListAccountsResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, 4 more }` Array of entity objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `relationships: map[object { cardinality, objectType, values, directions } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`. - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `directions: optional object { asDestination, asSource }` Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key. - `asDestination: object { cardinality, values }` The current record is the destination (incoming) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `asSource: object { cardinality, values }` The current record is the source (outgoing) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### Example ```http curl https://api.lightfield.app/v1/lists/$LIST_ID/accounts \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink", "relationships": { "foo": { "cardinality": "cardinality", "objectType": "objectType", "values": [ "string" ], "directions": { "asDestination": { "cardinality": "HAS_ONE", "values": [ "string" ] }, "asSource": { "cardinality": "HAS_ONE", "values": [ "string" ] } } } }, "updatedAt": "updatedAt", "externalId": "externalId" } ], "object": "object", "totalCount": 0 } ``` ## List contacts in a list **get** `/v1/lists/{listId}/contacts` Returns a paginated list of contacts that belong to the specified list. Results are sorted by when the record was created in Lightfield (`createdAt`), newest first. **[Required scopes](/using-the-api/scopes/):** `lists:read` and `contacts:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Path Parameters - `listId: string` Unique identifier of the list. ### Query Parameters - `limit: optional number` Maximum number of records to return. Defaults to 25, maximum 25. - `offset: optional number` Number of records to skip for pagination. Defaults to 0. ### Returns - `ListListContactsResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, 4 more }` Array of entity objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `relationships: map[object { cardinality, objectType, values, directions } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`. - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `directions: optional object { asDestination, asSource }` Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key. - `asDestination: object { cardinality, values }` The current record is the destination (incoming) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `asSource: object { cardinality, values }` The current record is the source (outgoing) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### Example ```http curl https://api.lightfield.app/v1/lists/$LIST_ID/contacts \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink", "relationships": { "foo": { "cardinality": "cardinality", "objectType": "objectType", "values": [ "string" ], "directions": { "asDestination": { "cardinality": "HAS_ONE", "values": [ "string" ] }, "asSource": { "cardinality": "HAS_ONE", "values": [ "string" ] } } } }, "updatedAt": "updatedAt", "externalId": "externalId" } ], "object": "object", "totalCount": 0 } ``` ## List opportunities in a list **get** `/v1/lists/{listId}/opportunities` Returns a paginated list of opportunities that belong to the specified list. Results are sorted by when the record was created in Lightfield (`createdAt`), newest first. **[Required scopes](/using-the-api/scopes/):** `lists:read` and `opportunities:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Path Parameters - `listId: string` Unique identifier of the list. ### Query Parameters - `limit: optional number` Maximum number of records to return. Defaults to 25, maximum 25. - `offset: optional number` Number of records to skip for pagination. Defaults to 0. ### Returns - `ListListOpportunitiesResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, 4 more }` Array of entity objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `relationships: map[object { cardinality, objectType, values, directions } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`. - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `directions: optional object { asDestination, asSource }` Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key. - `asDestination: object { cardinality, values }` The current record is the destination (incoming) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `asSource: object { cardinality, values }` The current record is the source (outgoing) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### Example ```http curl https://api.lightfield.app/v1/lists/$LIST_ID/opportunities \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink", "relationships": { "foo": { "cardinality": "cardinality", "objectType": "objectType", "values": [ "string" ], "directions": { "asDestination": { "cardinality": "HAS_ONE", "values": [ "string" ] }, "asSource": { "cardinality": "HAS_ONE", "values": [ "string" ] } } } }, "updatedAt": "updatedAt", "externalId": "externalId" } ], "object": "object", "totalCount": 0 } ``` ## Delete a list **delete** `/v1/lists/{id}` Moves a list to the trash. The list is soft-deleted and may be restored from the Lightfield UI. Member entities (accounts, contacts, or opportunities) are not affected. Calling delete on an already-trashed list is a no-op and returns the existing record. **[Required scope](/using-the-api/scopes/):** `lists:delete` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Path Parameters - `id: string` Unique identifier of the list to delete. ### Body Parameters - `body: optional object { }` ### Returns - `ListDeleteResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. ### Example ```http curl https://api.lightfield.app/v1/lists/$ID \ -X DELETE \ -H 'Lightfield-Version: 2026-03-01' \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "id": "id", "createdAt": "createdAt", "fields": { "foo": { "value": "string", "valueType": "ADDRESS" } }, "httpLink": "httpLink" } ``` ## Domain Types ### List Create Response - `ListCreateResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. ### List Delete Response - `ListDeleteResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. ### List List Accounts Response - `ListListAccountsResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, 4 more }` Array of entity objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `relationships: map[object { cardinality, objectType, values, directions } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`. - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `directions: optional object { asDestination, asSource }` Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key. - `asDestination: object { cardinality, values }` The current record is the destination (incoming) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `asSource: object { cardinality, values }` The current record is the source (outgoing) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### List List Contacts Response - `ListListContactsResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, 4 more }` Array of entity objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `relationships: map[object { cardinality, objectType, values, directions } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`. - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `directions: optional object { asDestination, asSource }` Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key. - `asDestination: object { cardinality, values }` The current record is the destination (incoming) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `asSource: object { cardinality, values }` The current record is the source (outgoing) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### List List Opportunities Response - `ListListOpportunitiesResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, 4 more }` Array of entity objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the entity in the Lightfield web app, or null. - `relationships: map[object { cardinality, objectType, values, directions } ]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`. - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: array of string` IDs of the related entities. - `directions: optional object { asDestination, asSource }` Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key. - `asDestination: object { cardinality, values }` The current record is the destination (incoming) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `asSource: object { cardinality, values }` The current record is the source (outgoing) endpoint. - `cardinality: "HAS_ONE" or "HAS_MANY"` Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`. - `"HAS_ONE"` - `"HAS_MANY"` - `values: array of string` IDs of the related entities in this direction. - `updatedAt: string` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId: optional string` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### List List Response - `ListListResponse object { data, object, totalCount }` - `data: array of object { id, createdAt, fields, httpLink }` Array of list objects for the current page. - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of lists matching the query. ### List Retrieve Response - `ListRetrieveResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null. ### List Update Response - `ListUpdateResponse object { id, createdAt, fields, httpLink }` - `id: string` Unique identifier for the list. - `createdAt: string` ISO 8601 timestamp of when the list was created. - `fields: map[object { value, valueType } ]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$objectType`). - `value: string or number or boolean or 3 more` The field value, or null if unset. - `string` - `number` - `boolean` - `array of string` - `Address object { city, country, latitude, 5 more }` - `city: optional string` City name. - `country: optional string` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: optional number` Latitude coordinate. - `longitude: optional number` Longitude coordinate. - `postalCode: optional string` Postal or ZIP code. - `state: optional string` State or province. - `street: optional string` Street address line 1. - `street2: optional string` Street address line 2. - `FullName object { firstName, lastName }` - `firstName: optional string` The contact's first name. - `lastName: optional string` The contact's last name. - `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string` URL to view the list in the Lightfield web app, or null.