Create lists and manage membership

Work with CRM data

Create a list, add or remove records, read its members, and delete the list without deleting its records.

Create a named collection of accounts, contacts or opportunities with the Lists API. Use Lists in the app for the product workflow; use List methods for filtering and pagination across resources.

Create an account list

Use a key with lists:create, lists:read and the read scope for the member type, such as accounts:read. Membership changes need lists:update; deletion needs lists:delete. Obtain real record IDs before adding them.

Create a list with its name and object type. Omit $kind for an ordinary list; target has a separate Target accounts purpose.

curl https://api.lightfield.app/v1/lists \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: northwind-renewals-list-001" \
  -d '{"fields":{"$name":"October renewals","$objectType":"$account"},"relationships":{"$accounts":["acc_northwind"]}}'

Save the returned id as LIST_ID. Check fields.$name.value and the object type. For contacts or opportunities, use $contact or $opportunity and the matching $contacts or $opportunities relationship.

Rename or change membership

Update the list with only the fields and membership operations you want to change:

curl "https://api.lightfield.app/v1/lists/$LIST_ID" \
  -X POST \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: northwind-renewals-list-002" \
  -d '{"fields":{"$name":"Q4 renewals"},"relationships":{"$accounts":{"add":["acc_contoso"],"remove":["acc_northwind"]}}}'

This changes membership; it does not delete either account. The member relationship must match the list’s object type. You cannot change $objectType through update; create another list for a different record type.

Verify the list and its members

Retrieve the list for its name and metadata. List lists when you need to recover a previously saved list ID.

curl "https://api.lightfield.app/v1/lists/$LIST_ID" \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01"

curl "https://api.lightfield.app/v1/lists?limit=20&offset=0" \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01"

curl "https://api.lightfield.app/v1/lists/$LIST_ID/accounts?limit=20&offset=0" \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01"

Choose list accounts, list contacts or list opportunities. Replace the final path segment accordingly. The response’s data contains readable member records. Continue increasing offset by limit until it reaches totalCount, even after a short or empty page: access filtering can remove records within a page.

Confirm added IDs appear and removed IDs no longer appear. Lists archived with their object definition are not returned, even for admins.

Delete the list

Delete moves only the list to trash. Its member records remain. The API has no list-restore operation; restore from Deleted items in Lightfield.

curl "https://api.lightfield.app/v1/lists/$LIST_ID" \
  -X DELETE \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01"

The returned record has the list’s ID. Deleting an already-trashed list is a no-op. For a rejected membership update, check the list type and IDs before retrying; a permission error requires the relevant list and record read scopes, not a new list.