Skip to main content
This page outlines the primary concepts you will encounter when working with the Lexful API. The exact model depends on your account configuration, but at a high level you should be familiar with:
  • API keys and tokens – how machine access is granted and authenticated.
  • Accounts and Organizations – how access is scoped and where data lives.
  • Assets and asset types – the flexible data model at the heart of Lexful.
  • Filtering – advanced property-level filtering with operators.
  • Paginating results – how list endpoints return results in pages.

​
API keys and tokens

API keys (ID and secret) are long-lived credentials you create in the Lexful dashboard. Use them to obtain short-lived Bearer tokens via the auth endpoint, and use those tokens on API calls.

​
Accounts

Lexful APIs are scoped by account. The X-Account-ID header identifies which account a request applies to. Within an account, you may have one or more organizations or similar entities.

​
Organizations

Organizations represent entities (companies, departments, teams, etc.) within your account. Every organization belongs to an account and can be classified with a type and a status, both of which are configurable via the API. Key characteristics:
  • Hierarchy – Organizations can have a parent_id, allowing you to model parent-child relationships.
  • Types and statuses – Use organization types (e.g., “client”, “vendor”) and statuses (e.g., “active”, “onboarding”) to categorize and filter organizations. Both support system-defined and custom values.
  • Asset scoping – Assets are scoped to an organization via organization_id. When listing assets you can filter by organization.
# List all active organizations
curl 'https://api.us.lexful.app/v1/organizations?status=active' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

​
Asset types

Asset types define the schema for a category of data in Lexful. Think of an asset type as a table definition — it declares the properties (fields) and references (relationships to other asset types) that its assets can have. Key characteristics:
  • System vs. custom – Some asset types are built-in (is_system: true). You can extend system types by adding properties or references prefixed with ext_. Custom asset types are fully user-defined.
  • Properties – Each property has a name and a type (string, number, boolean, date, richtext, and more). Properties define what data an asset of this type can hold.
  • References – Named links from one asset type to another, enabling you to model relationships (e.g., a “contract” asset type referencing a “vendor” asset type).
# List all asset types
curl 'https://api.us.lexful.app/v1/asset_types' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

​
Assets

Assets are the core data records in Lexful. Each asset belongs to an asset type and typically belongs to an organization. All asset endpoints are scoped by the asset type name in the URL path: /v1/assets/{assetTypeName}. Key characteristics:
  • CRUD – Create, read, update, and delete assets of any type. Deletes are soft-deletes (archiving); use include_deleted to retrieve archived records.
  • Filtering and search – List endpoints support filtering by organization_id, name, full-text search, field selection (fields), sorting, and pagination.
  • Reference expansion – Pass expand=references or expand=references.referenceName to inline related data in responses instead of making separate calls.
  • Related assets – Link assets to each other across types using the /v1/assets/{assetTypeName}/{assetId}/related endpoints.
  • Files – Attach files to assets and manage uploads and downloads through dedicated file endpoints.
  • Revisions – Every update to an asset is tracked. Use the revisions endpoints to view an asset’s change history or retrieve a specific past version.
  • Secure properties – Sensitive values can be stored encrypted and retrieved through a dedicated secure endpoint.
# List assets of a given type, scoped to an organization
curl 'https://api.us.lexful.app/v1/assets/contracts?organization_id={ORG_ID}' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

​
Filtering

When listing assets or organizations, you can go beyond simple query parameters and filter on any property using bracket notation: field[operator]=value.

​
Comparison operators

OperatorDescriptionExample
eqEqualsimportant[eq]=true
neNot equalsstatus[ne]=closed
gtGreater thanbudget[gt]=10000
gteGreater than or equalcreated_at[gte]=2024-01-01
ltLess thanbudget[lt]=50000
lteLess than or equalcreated_at[lte]=2024-12-31

​
Range and set operators

OperatorDescriptionExample
betweenBetween two values (comma-separated)budget[between]=10000,50000
inMatches any value in setcontact_type[in]=Decision Maker,Influencer
ninNot in setstatus[nin]=closed,archived
nullIs null / is not nulldeleted_at[null]=true

​
Text matching operators

OperatorDescriptionExample
likeCase-sensitive pattern matchname[like]=Acme%
ilikeCase-insensitive pattern matchname[ilike]=acme%
containsSubstring matchfirst_name[contains]=john
startswithStarts withname[startswith]=Project
endswithEnds withemail[endswith]=@example.com

​
Array operators

OperatorDescriptionExample
array_containsArray contains an exact object matchcontact_methods[array_contains]={"type":"Email"}
array_emptyArray is empty or notcontact_methods[array_empty]=false
array_length_eqArray length equalsmilestones[array_length_eq]=3
array_length_gtArray length greater thancontact_methods[array_length_gt]=0
array_length_gte, array_length_lt, array_length_lte, array_length_neOther array length comparisonsmilestones[array_length_gte]=1

​
Filtering by references

Filter assets by their references using dot notation: references.referenceName=id. Pass multiple IDs as a comma-separated list. 
# Find contacts at a specific location
curl 'https://api.us.lexful.app/v1/assets/system.contact?references.location={LOCATION_ID}&expand=references.location' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

​
Combining filters

Multiple filters can be combined in a single request. All filters are applied together (AND logic): 
# Important decision makers created this year with at least one contact method
curl 'https://api.us.lexful.app/v1/assets/system.contact?important[eq]=true&contact_type[in]=Decision Maker,Influencer&created_at[gte]=2024-01-01&contact_methods[array_length_gt]=0&sort=created_at&order=DESC' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

# Organizations whose name contains "acme", created after a specific date
curl 'https://api.us.lexful.app/v1/organizations?name[ilike]=acme%&created_at[gte]=2024-01-01' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

​
Paginating results

All list endpoints in the Lexful API use offset-based pagination with a consistent interface.

​
Request parameters

ParameterTypeDefaultDescription
limitnumber100Number of items to return (1–1000).
offsetnumber0Number of items to skip before returning results.

​
Response shape

Every paginated response includes these fields alongside the results:
FieldTypeDescription
itemsarrayThe page of results.
totalnumberTotal number of items available across all pages.
limitnumberThe limit that was applied.
offsetnumberThe offset that was applied.

​
Iterating through pages

Increment offset by limit on each request until offset >= total: 
# First page
curl 'https://api.us.lexful.app/v1/organizations?limit=50&offset=0' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

# Second page
curl 'https://api.us.lexful.app/v1/organizations?limit=50&offset=50' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'