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

# Create ICP

> Creates a new Ideal Customer Profile (ICP) for lead targeting

Creates a new ICP (Ideal Customer Profile) with the specified targeting criteria. The authenticated user is automatically added to the ICP's `userIds` array, granting them access to the newly created ICP.

## Authentication

This endpoint requires authentication. The user must be signed in to create an ICP.

<Note>
  The creating user is automatically added to the `userIds` array even if not
  explicitly included in the request body.
</Note>

## Request

<ParamField body="name" type="string" required>
  The name of the ICP. Should be descriptive of the target audience.
</ParamField>

<ParamField body="description" type="string | null">
  An optional description providing more context about the ICP's purpose and
  target criteria.
</ParamField>

<ParamField body="leadProviderCriteria" type="array" required>
  Array of lead provider search criteria. At least one criteria should be provided to enable lead sourcing.

  <Expandable title="Lead provider criteria object">
    <ParamField body="provider" type="string" required>
      The lead provider to use. Currently supports `"baseProvider"`.
    </ParamField>

    <ParamField body="type" type="string">
      The type of search to perform:

      * `"person"` - Search for individual contacts
      * `"company"` - Search for companies

      If omitted, defaults to person search (legacy behavior).
    </ParamField>

    <ParamField body="filters" type="object" required>
      Provider-specific filter object. For our base provider, this includes parameters like:

      * `job_title` - Array of job titles to target
      * `location` - Location filters (country, state, city)
      * `company` - Company filters (size, industry, keywords)
      * `skills` - Required skills
      * `seniority` - Seniority levels
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customFilterCriteria" type="array" required>
  Array of custom filters to apply after lead provider search. Can be empty array `[]` if no custom filters are needed.

  <Expandable title="Custom filter types">
    **Website Filter**

    ```json theme={null}
    {
      "type": "website",
      "provider": "browserUse",
      "prompt": "Check if company offers B2B SaaS products"
    }
    ```

    **Web Scraping Filter**

    ```json theme={null}
    {
      "type": "webscraping",
      "provider": "firecrawl",
      "extractionPrompt": "Extract pricing information",
      "pageFindingPrompt": "Find the pricing page",
      "includeSearchStrings": ["enterprise", "pricing"],
      "excludeSearchStrings": ["free trial only"]
    }
    ```

    **AI Filter**

    ```json theme={null}
    {
      "type": "ai",
      "entityType": "person",
      "prompt": "Evaluate if this person has hiring authority"
    }
    ```

    **Max People Per Company**

    ```json theme={null}
    {
      "type": "maxPeoplePerCompany",
      "value": 2
    }
    ```

    **Max Percent From CRM**

    ```json theme={null}
    {
      "type": "maxPercentFromCRM",
      "value": 50
    }
    ```

    **Min Days Until Reuse**

    ```json theme={null}
    {
      "type": "minDaysUntilReuse",
      "value": 180
    }
    ```

    **Match Field With Regex**

    ```json theme={null}
    {
      "type": "matchFieldWithRegex",
      "field": "company.name",
      "regex": "^(?!.*Test).*$"
    }
    ```
  </Expandable>
</ParamField>

<ParamField body="crmFilters" type="object | null | undefined">
  Optional CRM integration filters for sourcing leads from connected CRM systems. This field is both optional and nullable.

  <Expandable title="CRM filters object">
    <ParamField body="provider" type="string" required>
      CRM provider. Currently supports `"bullhorn"`.
    </ParamField>

    <ParamField body="textSearch" type="string | null | undefined">
      Free-text search for occupation/title field. Supports wildcards and boolean operators (e.g., `"Head OR Leit* OR Direktor"`). This field is both optional and nullable.
    </ParamField>

    <ParamField body="query" type="string | null | undefined">
      Legacy query field. Optional and nullable. Retained for backward compatibility.
    </ParamField>

    <ParamField body="filters" type="array">
      Array of structured filter conditions.

      <Expandable title="Filter condition object">
        <ParamField body="path" type="string" required>
          Field path using dot notation (e.g., `"address.zip"`, `"status"`).
        </ParamField>

        <ParamField body="mode" type="string" required>
          Match mode: `"equals"`, `"in"`, or `"startsWith"`.
        </ParamField>

        <ParamField body="value" type="string | array">
          Value(s) to match. Use string for `equals`/`startsWith`, array for `in` mode.
        </ParamField>

        <ParamField body="exclude" type="boolean" default="false">
          If `true`, exclude contacts matching this condition.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="userIds" type="array" required>
  Array of Clerk user IDs that should have access to this ICP. The creating user
  is automatically included.
</ParamField>

<ParamField body="leadsPerList" type="number" default={10}>
  Number of leads to include per generated lead list.
</ParamField>

<ParamField body="activeUntil" type="string | null">
  ISO 8601 timestamp indicating when the ICP should expire. Set to `null` for no
  expiration.
</ParamField>

## Response

Returns the created ICP object.

<ResponseField name="id" type="string" required>
  The generated UUID for the new ICP.
</ResponseField>

<ResponseField name="name" type="string" required>
  The name of the ICP.
</ResponseField>

<ResponseField name="description" type="string | null" required>
  The description of the ICP.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp of when the ICP was created.
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  ISO 8601 timestamp of when the ICP was last updated (same as createdAt for new
  ICPs).
</ResponseField>

<ResponseField name="leadProviderCriteria" type="array" required>
  The lead provider search criteria as provided in the request.
</ResponseField>

<ResponseField name="customFilterCriteria" type="array" required>
  The custom filter criteria as provided in the request.
</ResponseField>

<ResponseField name="crmFilters" type="object | null | undefined">
  The CRM filters as provided in the request. This field is both optional and nullable.
</ResponseField>

<ResponseField name="userIds" type="array" required>
  Array of user IDs with access, including the creating user.
</ResponseField>

<ResponseField name="leadsPerList" type="number" required>
  Number of leads per list.
</ResponseField>

<ResponseField name="activeUntil" type="string | null" required>
  Expiration timestamp or `null`.
</ResponseField>

## Request Examples

<CodeGroup>
  ```json Basic ICP theme={null}
  {
    "name": "DACH Tech Leaders",
    "description": "Technology leaders in German-speaking regions",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["CTO", "VP Engineering", "Head of Technology"],
          "location": {
            "country": ["Germany", "Austria", "Switzerland"]
          },
          "company": {
            "employee_size": {
              "min": 100,
              "max": 5000
            }
          }
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "maxPeoplePerCompany",
        "value": 2
      }
    ],
    "crmFilters": null,
    "userIds": [],
    "leadsPerList": 20,
    "activeUntil": null
  }
  ```

  ```json ICP with CRM Integration theme={null}
  {
    "name": "Existing Contacts - Refresh",
    "description": "Re-engage existing CRM contacts in specific regions",
    "leadProviderCriteria": [],
    "customFilterCriteria": [
      {
        "type": "minDaysUntilReuse",
        "value": 90
      }
    ],
    "crmFilters": {
      "provider": "bullhorn",
      "textSearch": "Director OR Manager",
      "filters": [
        {
          "path": "address.countryName",
          "mode": "in",
          "value": ["Germany", "Austria"],
          "exclude": false
        },
        {
          "path": "status",
          "mode": "equals",
          "value": "Active",
          "exclude": false
        }
      ]
    },
    "userIds": ["user_teammate123"],
    "leadsPerList": 50,
    "activeUntil": "2024-12-31T23:59:59.000Z"
  }
  ```

  ```json ICP with AI Filtering theme={null}
  {
    "name": "AI-Qualified SaaS Buyers",
    "description": "Leads qualified by AI for SaaS purchasing intent",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": [
            "IT Manager",
            "Procurement Manager",
            "Operations Director"
          ],
          "company": {
            "industry": ["Technology", "Finance", "Healthcare"]
          }
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "ai",
        "entityType": "company",
        "prompt": "Determine if this company is likely to purchase B2B SaaS solutions based on their industry, size, and technology stack"
      },
      {
        "type": "website",
        "provider": "browserUse",
        "prompt": "Check if the company website mentions digital transformation or cloud adoption initiatives"
      },
      {
        "type": "maxPeoplePerCompany",
        "value": 3
      }
    ],
    "crmFilters": null,
    "userIds": [],
    "leadsPerList": 15,
    "activeUntil": null
  }
  ```
</CodeGroup>

## Response Examples

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "DACH Tech Leaders",
    "description": "Technology leaders in German-speaking regions",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["CTO", "VP Engineering", "Head of Technology"],
          "location": {
            "country": ["Germany", "Austria", "Switzerland"]
          },
          "company": {
            "employee_size": {
              "min": 100,
              "max": 5000
            }
          }
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "maxPeoplePerCompany",
        "value": 2
      }
    ],
    "crmFilters": null,
    "userIds": ["user_abc123"],
    "leadsPerList": 20,
    "activeUntil": null
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Invalid request body",
      "details": [
        {
          "path": ["name"],
          "message": "Required"
        }
      ]
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "User not authenticated"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code       | Description                                                                     |
| ----------- | ---------------- | ------------------------------------------------------------------------------- |
| 400         | `BAD_REQUEST`    | Invalid request body. Check the `details` field for specific validation errors. |
| 401         | `UNAUTHORIZED`   | User is not authenticated. Ensure a valid session exists.                       |
| 500         | `INTERNAL_ERROR` | An unexpected server error occurred.                                            |