List methods

List endpoints return pages of records. Use limit and offset to paginate, and field or relationship filters to narrow the result. This guide uses List accounts, List contacts and List opportunities.

List results can lag behind recent changes. Use the individual Retrieve method when you need the latest version of a record.

Pagination

Use these parameters to request each page:

• offset: The number of matching records to skip.
• limit: The maximum number of records in each page, from 1 to 25.

Advance offset by limit until it reaches totalCount, even when a page is short or empty. Each page includes only records you can currently read, while totalCount can include records you can no longer read. For example, with limit=25 and totalCount=60, request offsets 0, 25 and 50; do not stop if the first page contains only 20 records.

Do not reuse an offset as a durable bookmark. Records can move between pages as the result set changes.

Filtering

The available filter operators are equal, startsWith, contains, greaterThan, greaterThanOrEqual, lessThan, and lessThanOrEqual. Which ones you can use depends on the data type of the field you filter by.

Filtering by fields

Data Type	equal 2	greaterThan, etc.	startsWith	contains 2
NUMBER	yes	yes	no	no
CURRENCY	yes	yes	no	no
DATETIME	yes	yes	no	no
TEXT	yes	no	yes	no
FULL_NAME	yes	no	yes	no
SOCIAL_HANDLE	yes	no	yes	no
ADDRESS	yes	no	yes	no
CHECKBOX	yes	no	no	no
SINGLE_SELECT	yes	no	no	no
EMAIL	no	no	no	yes
TELEPHONE	no	no	no	yes
URL	no	no	no	yes
MULTI_SELECT 1	no	no	no	no
MARKDOWN1	no	no	no	no

¹

A row with only no entries means that data type does not yet support filtering.

²

If you omit the operator, the API uses equal when supported and contains otherwise.

To filter a SINGLE_SELECT field, pass either the option’s id from the object’s definitions, such as opt_abc123, or its label. An ID keeps working after someone renames the option. Stages have their own rules, described next.

Filtering by pipeline and stage

Read the object type’s definitions for $pipeline and the stages it owns. Use the returned pipeline ID for a $pipeline[equal] filter; pipeline names are accepted as write hints, not filter values.

# Find opportunities in a particular stage of the Renewals pipeline.
# Replace these placeholder IDs with values from definitions.
curl https://api.lightfield.app/v1/opportunities \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$pipeline[equal]=pd_renewals' \
  --data-urlencode '$stage[equal]=opt_renewals_qualified'

A stage option ID identifies the stage without needing a pipeline filter. You can also filter by a stage label, such as $stage[equal]=Qualified. If that label exists in multiple pipelines, add a positive $pipeline[equal] filter or use the exact stage option ID. Ambiguous labels return 400 with ambiguous_stage_label; an unknown pipeline returns 400 with unknown_pipeline. See pipeline errors.

Only one positive pipeline filter is allowed. $pipeline[-equal] excludes a pipeline but does not disambiguate a stage label. Filters are AND-ed: a stage option ID combined with a different pipeline matches no records. Unlike Opportunity label writes, label filters do not default to the opportunity’s default pipeline.

Filtering by relationships

You can also filter by relationships to find records linked to a specific entity. Use the relationship definition slug from the definitions endpoint as the filter key, and pass the ID of the related entity as the value.

Relationship filters support the contains operator (checks if the entity ID is in the relationship) and equal (which behaves the same as contains for relationships). If no operator is specified, contains is used by default.

# Find tasks associated with a specific account
curl https://api.lightfield.app/v1/tasks \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$task-account[contains]=acc_abc123'

# Find accounts linked to a specific contact
curl https://api.lightfield.app/v1/accounts \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$account-contact[contains]=con_def456'

# Combine field and relationship filters:
# find open tasks for a specific account
curl https://api.lightfield.app/v1/tasks \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$task-account[contains]=acc_abc123' \
  --data-urlencode '$status[equal]=TODO'

For a self-referential relationship, the plain key matches the related record in either role. Append :asSource or :asDestination to match only the role the returned records play:

# Find the subsidiaries of acc_parent (accounts in the destination role)
curl https://api.lightfield.app/v1/accounts \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode 'account-hierarchy:asDestination[contains]=acc_parent'

# Find the parent of acc_sub1 (the account in the source role)
curl https://api.lightfield.app/v1/accounts \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode 'account-hierarchy:asSource[contains]=acc_sub1'

Relationship filters use the relationship definition slug, not the relationship response key. For self-referential relationships, the directional form is the slug followed by :asSource or :asDestination. Use the definitions endpoint to discover the available relationship slugs for an object type.

All operators can be negated by prefixing them with -; for instance, -equal means “everything not equal to this value”.

Operator names must match exactly. A misspelled operator, such as equals or startWith, returns 400. A key that isn’t in the field[operator] form, such as $name[starts-with], is ignored rather than rejected, so that filter is silently dropped.

Find an existing account or contact

Before creating a record, search for an existing one that matches so Lightfield does not accumulate duplicates.

# Check if the Lightfield account exists.
curl https://api.lightfield.app/v1/accounts \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$name[equal]=lightfield'

# Check if a contact exists with a given email.
curl https://api.lightfield.app/v1/contacts \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$email[contains]=example@lightfield.app'

Combine filters

# Find accounts in the 10,001+ employee band AND
# an ICP score lower than 6. ICP score is a user-defined attribute.
curl https://api.lightfield.app/v1/accounts \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$headcount[equal]=10001+' \
  --data-urlencode 'icp-score[lessThan]=6'

# Find very valuable opportunities that had an
# interaction since March 1st, 2026.
curl https://api.lightfield.app/v1/opportunities \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$amount[greaterThanOrEqual]=100000000' \
  --data-urlencode '$lastInteractionAt[greaterThanOrEqual]=2026-03-01T00:00:00.000Z'

You can query a field that supports startsWith with an empty string to find all records that have that value set, but not empty.

# Find all C-suite executives that we can reach out
# to through Instagram, except Alice Bob.
curl https://api.lightfield.app/v1/contacts \
  -G \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  --data-urlencode '$doNotContact[equal]=false' \
  --data-urlencode '$instagram[startsWith]=' \
  --data-urlencode '$title[startsWith]=Chief' \
  --data-urlencode '$name[-equal]=Alice Bob'

Related documentation

• In the app: tables, views and exports. API filters apply to requests; they do not create a saved UI view.
• Endpoint contracts: list accounts, contacts and opportunities.