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

# Export to CRM

> Export selected leads to a connected CRM system (Bullhorn or Close)

## Overview

This endpoint exports leads from Lance to your connected CRM. It supports bulk selection of leads and configurable duplicate handling strategies.

## Authentication

<Note>
  This endpoint requires authentication. The organization ID is automatically
  extracted from the authenticated session.
</Note>

## Request Body

<ParamField body="selection" type="object" required>
  Defines which leads to export using bulk selection.

  <Expandable title="selection properties">
    <ParamField body="selection.mode" type="string" required>
      Selection mode. Either `manual` for explicit row selection or `bulk` for intent-based selection.

      Allowed values: `manual`, `bulk`
    </ParamField>

    <ParamField body="selection.startIndex" type="integer">
      Starting index for bulk selection (0-based). Required when `mode` is `bulk`.
    </ParamField>

    <ParamField body="selection.targetCount" type="integer">
      Number of items to select in bulk mode. Maximum: 1000. Required when `mode` is `bulk`.
    </ParamField>

    <ParamField body="selection.excludedIds" type="string[]">
      Array of lead IDs to exclude from the bulk selection range.
    </ParamField>

    <ParamField body="selection.includedIds" type="string[]">
      Array of lead IDs to explicitly include. Used for manual mode or additions outside the bulk range.
    </ParamField>

    <ParamField body="selection.filters" type="object">
      Search filters to reproduce the exact query. Required when `mode` is `bulk`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="options" type="object" required>
  Export configuration options.

  <Expandable title="options properties">
    <ParamField body="options.provider" type="string" required>
      Target CRM provider. Must match your connected CRM.

      Allowed values: `close`, `bullhorn`
    </ParamField>

    <ParamField body="options.checkForDuplicates" type="boolean" default={true}>
      Whether to check for existing contacts/leads in the CRM before creating.
    </ParamField>

    <ParamField body="options.duplicateHandling" type="string" default="skip">
      Strategy for handling duplicates when a matching contact exists.

      Allowed values:

      * `skip` - Skip if lead/contact already exists
      * `update` - Update existing lead/contact with new data
      * `create_duplicate` - Create a new entry even if duplicate exists
    </ParamField>

    <ParamField body="options.createNewHandling" type="string" default="create">
      Strategy when a contact doesn't exist in the CRM.

      Allowed values:

      * `create` - Create a new Lead with Contact
      * `skip` - Skip this lead entirely
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Whether the overall export operation completed successfully.
</ResponseField>

<ResponseField name="totalProcessed" type="integer" required>
  Total number of leads processed in this export.
</ResponseField>

<ResponseField name="created" type="integer" required>
  Number of new contacts/leads created in the CRM.
</ResponseField>

<ResponseField name="updated" type="integer" required>
  Number of existing contacts/leads updated in the CRM.
</ResponseField>

<ResponseField name="skipped" type="integer" required>
  Number of leads skipped (due to duplicate handling or other rules).
</ResponseField>

<ResponseField name="failed" type="integer" required>
  Number of leads that failed to export.
</ResponseField>

<ResponseField name="results" type="array" required>
  Detailed results for each lead processed.

  <Expandable title="results item properties">
    <ResponseField name="results[].leadId" type="string" required>
      Lance lead ID.
    </ResponseField>

    <ResponseField name="results[].personName" type="string" required>
      Name of the person/lead.
    </ResponseField>

    <ResponseField name="results[].companyName" type="string | null" required>
      Company name associated with the lead.
    </ResponseField>

    <ResponseField name="results[].status" type="string" required>
      Export status for this lead.

      Possible values: `created`, `updated`, `skipped`, `failed`
    </ResponseField>

    <ResponseField name="results[].crmLeadId" type="string">
      CRM lead/company ID if created or updated.
    </ResponseField>

    <ResponseField name="results[].crmContactId" type="string">
      CRM contact ID if created or updated.
    </ResponseField>

    <ResponseField name="results[].error" type="string">
      Error message if the export failed for this lead.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errors" type="string[]">
  Array of general error messages encountered during export.
</ResponseField>

## Error Responses

| Status Code | Error                      | Description                                    |
| ----------- | -------------------------- | ---------------------------------------------- |
| 400         | `Organization ID required` | No authenticated organization found            |
| 400         | `CRM is not connected`     | Organization has no CRM integration configured |
| 400         | `CRM provider mismatch`    | Requested provider doesn't match connected CRM |
| 400         | `Invalid request`          | Request body validation failed                 |

<RequestExample>
  ```json Manual Selection theme={null}
  {
    "selection": {
      "mode": "manual",
      "includedIds": [
        "lead_abc123",
        "lead_def456",
        "lead_ghi789"
      ]
    },
    "options": {
      "provider": "bullhorn",
      "checkForDuplicates": true,
      "duplicateHandling": "skip",
      "createNewHandling": "create"
    }
  }
  ```

  ```json Bulk Selection theme={null}
  {
    "selection": {
      "mode": "bulk",
      "startIndex": 0,
      "targetCount": 100,
      "excludedIds": ["lead_xyz999"],
      "filters": {
        "job_titles": ["Software Engineer", "Developer"],
        "locations": ["San Francisco, CA"]
      }
    },
    "options": {
      "provider": "close",
      "checkForDuplicates": true,
      "duplicateHandling": "update",
      "createNewHandling": "create"
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "totalProcessed": 3,
    "created": 2,
    "updated": 0,
    "skipped": 1,
    "failed": 0,
    "results": [
      {
        "leadId": "lead_abc123",
        "personName": "Jane Smith",
        "companyName": "Acme Corp",
        "status": "created",
        "crmLeadId": "crm_lead_001",
        "crmContactId": "crm_contact_001"
      },
      {
        "leadId": "lead_def456",
        "personName": "John Doe",
        "companyName": "Tech Inc",
        "status": "created",
        "crmLeadId": "crm_lead_002",
        "crmContactId": "crm_contact_002"
      },
      {
        "leadId": "lead_ghi789",
        "personName": "Bob Wilson",
        "companyName": "StartupXYZ",
        "status": "skipped"
      }
    ]
  }
  ```

  ```json 200 - Empty Selection theme={null}
  {
    "success": true,
    "totalProcessed": 0,
    "created": 0,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "results": []
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
    "error": "CRM is not connected"
  }
  ```
</ResponseExample>