> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lexful.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Flows

> Example end-to-end flows using the Lexful API.

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

<Steps>
  <Step title="Get a token">
    Use your API key ID and secret to obtain a Bearer token:

    ```bash theme={null}
    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}"
      }'
    ```
  </Step>

  <Step title="List organizations">
    Call the organizations endpoint with the token and account ID:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Flow: Create an organization and add assets

<Steps>
  <Step title="Create an organization">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Create an asset in that organization">
    ```bash theme={null}
    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" }
        ]
      }'
    ```
  </Step>

  <Step title="Verify the asset was created">
    ```bash theme={null}
    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}'
    ```
  </Step>
</Steps>

## Flow: Filter and sort assets

Use bracket-notation operators to build precise queries. See <a href="/guides/core-concepts#filtering">Filtering</a> for the full operator reference.

<Steps>
  <Step title="Filter by property values">
    Find important contacts of a specific type:

    ```bash theme={null}
    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}'
    ```
  </Step>

  <Step title="Add date ranges and sorting">
    Narrow to contacts created this year, newest first:

    ```bash theme={null}
    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}'
    ```
  </Step>

  <Step title="Select specific fields">
    Return only the fields you need to reduce payload size:

    ```bash theme={null}
    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}'
    ```
  </Step>
</Steps>

## 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 <a href="/guides/core-concepts#paginating-results">Paginating results</a> for details.

<Steps>
  <Step title="Fetch the first page">
    ```bash theme={null}
    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 }`.
  </Step>

  <Step title="Fetch subsequent pages">
    Increment `offset` by `limit` until you have all results:

    ```bash theme={null}
    # 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`.
  </Step>
</Steps>

## Flow: Link related assets

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

<Steps>
  <Step title="Add a related asset">
    Link a contact to a configuration asset:

    ```bash theme={null}
    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"
        }
      ]'
    ```
  </Step>

  <Step title="List related assets">
    ```bash theme={null}
    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.
  </Step>
</Steps>

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

<Steps>
  <Step title="Create a file record">
    This returns a presigned S3 upload URL:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Upload the file">
    Use the presigned URL to upload the file directly to storage:

    ```bash theme={null}
    curl -X PUT '{PRESIGNED_UPLOAD_URL}' \
      --header 'Content-Type: application/pdf' \
      --data-binary '@resume.pdf'
    ```
  </Step>

  <Step title="Mark the upload as complete">
    ```bash theme={null}
    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}'
    ```
  </Step>

  <Step title="Download the file later">
    Get a presigned download URL:

    ```bash theme={null}
    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}'
    ```
  </Step>
</Steps>