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

# Get ICP

> Retrieves a single ICP (Ideal Customer Profile) by its ID

Retrieves the full details of an ICP (Ideal Customer Profile) by its unique identifier. ICPs define the criteria used to search for and filter leads from various providers, including lead provider search criteria, custom filtering rules, and CRM filters.

## Authentication

This endpoint requires authentication. The user must be signed in.

<Note>
  Users can only access ICPs where they are listed in the `userIds` array, or if
  they are an admin user. Attempting to access an ICP without proper
  authorization will result in a 403 Forbidden error.
</Note>

## Request

<ParamField path="id" type="string" required>
  The unique identifier (UUID) of the ICP to retrieve.
</ParamField>

## Response

Returns the complete ICP object.

<ResponseField name="id" type="string" required>
  Unique identifier (UUID) for the ICP.
</ResponseField>

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

<ResponseField name="description" type="string | null" required>
  A description of the ICP's target profile. May be `null`.
</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.
</ResponseField>

<ResponseField name="userIds" type="array" required>
  Array of Clerk user IDs that have access to this ICP.
</ResponseField>

<ResponseField name="leadsPerList" type="number" required>
  The default number of leads to include when generating lead lists from this
  ICP. Defaults to 10.
</ResponseField>

<ResponseField name="activeUntil" type="string | null" required>
  ISO 8601 timestamp indicating when the ICP expires. May be `null` for
  indefinite ICPs.
</ResponseField>

<ResponseField name="leadProviderCriteria" type="array" required>
  Array of search criteria configurations for lead providers.

  <Expandable title="Lead provider criteria object properties">
    <ResponseField name="provider" type="string" required>
      The lead provider identifier (e.g., `"baseProvider"`).
    </ResponseField>

    <ResponseField name="type" type="string">
      The search type: `"person"` or `"company"`. If omitted, defaults to `"person"` (legacy format).
    </ResponseField>

    <ResponseField name="filters" type="object" required>
      Provider-specific filter configuration for the search.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customFilterCriteria" type="array" required>
  Array of custom filtering rules applied to leads after retrieval.

  <Expandable title="Custom filter types">
    <ResponseField name="type" type="string" required>
      The filter type. One of: `"website"`, `"webscraping"`, `"ai"`, `"maxPeoplePerCompany"`, `"maxPercentFromCRM"`, `"minDaysUntilReuse"`, `"matchFieldWithRegex"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="crmFilters" type="object | null | undefined">
  Optional CRM filter configuration for integrations like Bullhorn. This field is both optional and nullable.

  <Expandable title="CRM filters properties">
    <ResponseField name="provider" type="string" required>
      The CRM provider (currently only `"bullhorn"`).
    </ResponseField>

    <ResponseField name="textSearch" type="string | null | undefined">
      Free-text search for occupation/title field. This field is both optional and nullable.
    </ResponseField>

    <ResponseField name="filters" type="array">
      Array of structured filter conditions with `path`, `mode`, `value`, and `exclude` properties.
    </ResponseField>

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

## Response Examples

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Enterprise Tech Decision Makers",
    "description": "C-level and VP-level technology leaders at enterprise companies",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:22:00.000Z",
    "userIds": ["user_abc123", "user_def456"],
    "leadsPerList": 25,
    "activeUntil": "2024-12-31T23:59:59.000Z",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_titles": ["CTO", "VP Engineering", "Head of Technology"],
          "company_size": ["501-1000", "1001-5000", "5001+"]
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "maxPeoplePerCompany",
        "value": 3
      },
      {
        "type": "minDaysUntilReuse",
        "value": 180
      }
    ],
    "crmFilters": null
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "message": "You do not have access to this ICP"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "ICP not found: 550e8400-e29b-41d4-a716-446655440000"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code       | Description                                               |
| ----------- | ---------------- | --------------------------------------------------------- |
| 401         | `UNAUTHORIZED`   | User is not authenticated. Ensure a valid session exists. |
| 403         | `FORBIDDEN`      | User does not have access to this ICP.                    |
| 404         | `NOT_FOUND`      | No ICP exists with the specified ID.                      |
| 500         | `INTERNAL_ERROR` | An unexpected server error occurred.                      |