Common Flows - Lexful Docs

This page collects a few common flows you might implement with the Lexful API. As you gain more usage patterns, you can replace or extend these examples with the actual flows that matter most to your customers.

Flow: Authenticate and list organizations

Get a token

Use your API key ID and secret to obtain a Bearer token:

curl --location 'https://api.us.lexful.app/v1/auth/token' \
  --header 'X-Account-Id: {YOUR_ACCOUNT_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "{YOUR_API_KEY_ID}",
    "secret": "{YOUR_API_KEY_SECRET}"
  }'

List organizations

Call the organizations endpoint with the token and account ID:

curl --location 'https://api.us.lexful.app/v1/organizations' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

The response includes organizations accessible to your account.

Flow: Create an organization and add assets

Create an organization

curl -X POST 'https://api.us.lexful.app/v1/organizations' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Corporation",
    "type": "client",
    "status": "active"
  }'

Save the id from the response — you will use it as the organization_id when creating assets.

Create an asset in that organization

curl -X POST 'https://api.us.lexful.app/v1/assets/system.contact' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "organization_id": "{ORG_ID}",
    "first_name": "Jane",
    "last_name": "Smith",
    "title": "VP of Engineering",
    "important": false,
    "contact_type": "Influencer",
    "contact_methods": [
      { "type": "Email", "value": "jane.smith@example.com" }
    ]
  }'

Verify the asset was created

curl 'https://api.us.lexful.app/v1/assets/system.contact?organization_id={ORG_ID}' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

Flow: Filter and sort assets

Use bracket-notation operators to build precise queries. See Filtering for the full operator reference.

Filter by property values

Find important contacts of a specific type:

curl 'https://api.us.lexful.app/v1/assets/system.contact?important[eq]=true&contact_type[in]=Decision Maker,Influencer' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

Add date ranges and sorting

Narrow to contacts created this year, newest first:

curl 'https://api.us.lexful.app/v1/assets/system.contact?important[eq]=true&created_at[gte]=2024-01-01&sort=created_at&order=DESC' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

Select specific fields

Return only the fields you need to reduce payload size:

curl 'https://api.us.lexful.app/v1/assets/system.contact?important[eq]=true&fields=first_name,last_name,title,contact_methods' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

Flow: Paginate through a large result set

When a collection has more items than a single page can return, iterate using limit and offset. See Paginating results for details.

Fetch the 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}'

The response includes total, limit, and offset. For example: { "items": [...], "total": 120, "limit": 50, "offset": 0 }.

Fetch subsequent pages

Increment offset by limit until you have all results:

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

# Page 3 (final — offset 100 + limit 50 covers remaining 20)
curl 'https://api.us.lexful.app/v1/organizations?limit=50&offset=100' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

Stop when offset >= total.

Related assets let you create ad-hoc relationships between any two assets, even across different asset types.

Add a related asset

Link a contact to a configuration asset:

curl -X PUT 'https://api.us.lexful.app/v1/assets/system.contact/{CONTACT_ID}/related' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "asset_id": "{CONFIGURATION_ID}",
      "description": "Primary contact for this configuration"
    }
  ]'

List related assets

curl 'https://api.us.lexful.app/v1/assets/system.contact/{CONTACT_ID}/related' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

The response includes each linked asset’s type, ID, name, and description.

Flow: Upload a file to an asset

File uploads use a three-step process: create the file record, upload to the presigned URL, then mark the upload as complete.

Create a file record

This returns a presigned S3 upload URL:

curl -X POST 'https://api.us.lexful.app/v1/assets/system.contact/{CONTACT_ID}/files' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "resume",
    "original_name": "resume.pdf",
    "file_extension": ".pdf",
    "mime_type": "application/pdf",
    "size": 204800
  }'

Save the file.id and presignedUploadUrl from the response.

Upload the file

Use the presigned URL to upload the file directly to storage:

curl -X PUT '{PRESIGNED_UPLOAD_URL}' \
  --header 'Content-Type: application/pdf' \
  --data-binary '@resume.pdf'

Mark the upload as complete

curl -X POST 'https://api.us.lexful.app/v1/assets/system.contact/{CONTACT_ID}/files/{FILE_ID}/complete' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

Download the file later

Get a presigned download URL:

curl 'https://api.us.lexful.app/v1/assets/system.contact/{CONTACT_ID}/files/{FILE_ID}/download' \
  --header 'X-Account-ID: {YOUR_ACCOUNT_ID}' \
  --header 'Authorization: Bearer {TOKEN}'

​Flow: Authenticate and list organizations

​Flow: Create an organization and add assets

​Flow: Filter and sort assets

​Flow: Paginate through a large result set

​Flow: Link related assets

​Flow: Upload a file to an asset

Flow: Authenticate and list organizations

Flow: Create an organization and add assets

Flow: Filter and sort assets

Flow: Paginate through a large result set

Flow: Link related assets

Flow: Upload a file to an asset