---
title: Create lists and manage membership | Lightfield
description: 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](/help/lists/index.md) for the product workflow; use [List methods](/using-the-api/list-endpoints/index.md) 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](/api/resources/list/methods/create/index.md) with its name and object type. Omit `$kind` for an ordinary list; `target` has a separate [Target accounts](/help/target-accounts/index.md) purpose.

Terminal window

```
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](/api/resources/list/methods/update/index.md) with only the fields and membership operations you want to change:

Terminal window

```
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](/api/resources/list/methods/retrieve/index.md) for its name and metadata. [List lists](/api/resources/list/methods/list/index.md) when you need to recover a previously saved list ID.

Terminal window

```
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](/api/resources/list/methods/listAccounts/index.md), [list contacts](/api/resources/list/methods/listContacts/index.md) or [list opportunities](/api/resources/list/methods/listOpportunities/index.md). 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](/api/resources/list/methods/delete/index.md) moves only the list to trash. Its member records remain. The API has no list-restore operation; restore from [Deleted items](/help/deleted-items/index.md) in Lightfield.

Terminal window

```
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.