> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/icp-enrichment/create-icp.md).

# Create ICP

Create an ICP from a natural-language description; returns the saved ICP and its id.

## Create ICP

<mark style="color:green;">`POST`</mark> `/create_icp`

{% hint style="info" %}
Free — no credits are charged. Every response still returns `credits_used` and `credits_remaining`.
{% endhint %}

Create an ICP (Ideal Customer Profile) from a natural-language description. The text is parsed into structured filters and a match threshold, and the saved ICP is returned including its `id` (used by the scoring endpoints). A `name` you already use on another ICP is refused with `name_in_use` and the existing ICP's id; change that ICP with Update ICP instead. All ICP routes are scoped to the caller — another account's `icp_id` returns 404.

{% hint style="info" %}
ICP scoring is a 3-step async flow: (1) create an ICP here, (2) start scoring with `/run_enrichment`, (3) poll results with `/get_enrichment`.
{% endhint %}

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

| Name              | Type         | Description                                                      |
| ----------------- | ------------ | ---------------------------------------------------------------- |
| `api_key`         | string       | Your API Key.                                                    |
| `nl_text`         | string       | Required. Natural-language ICP description.                      |
| `name`            | string       | Optional. Defaults to the extracted name.                        |
| `match_threshold` | number (0–1) | Optional. Match cutoff. Defaults to the extracted value, or 0.7. |

**Response**

| Field inside `data` | Type    | Description                                     |
| ------------------- | ------- | ----------------------------------------------- |
| `id`                | integer | The ICP id. Pass it to the other ICP endpoints. |
| `name`              | string  | ICP name.                                       |
| `summary`           | string  | Plain-English summary of who the ICP targets.   |
| `nl_text`           | string  | The description you sent.                       |
| `params`            | object  | The structured filters parsed out of the text.  |
| `match_threshold`   | number  | Match cutoff used when scoring.                 |
| `is_active`         | boolean | Whether the ICP is marked active.               |
| `created_at`        | string  | When the ICP was created.                       |
| `updated_at`        | string  | When the ICP was last changed.                  |

The record is under `data`. See [Response Format](/getting-started/response-format.md) for the fields every endpoint returns.

**Example**

{% tabs %}
{% tab title="Input" %}

```json
{
  "api_key": "your_api_key",
  "nl_text": "CTOs at seed-stage fintech startups in the US",
  "name": "CTOs at Seed-Stage Fintech",
  "match_threshold": 0.7
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "success",
  "data": {
    "id": 28,
    "user_id": "mem_xxxxxxxxxxxx",
    "name": "CTOs at Seed-Stage Fintech",
    "summary": "Targeting Chief Technology Officers at early-stage financial technology companies in the United States.",
    "nl_text": "CTOs at seed-stage fintech startups in the US",
    "params": {
      "icp_name": "CTOs at Seed-Stage Fintech Startups",
      "match_threshold": 0.7,
      "semantic_criteria": [
        {"id": "cto", "weight": 1.0, "description": "The contact must hold the title of Chief Technology Officer.", "hard_requirement": true},
        {"id": "fintech", "weight": 1.0, "description": "The company must operate within the financial technology industry.", "hard_requirement": true}
      ],
      "deterministic_filters": {
        "country": ["United States"],
        "function": ["Engineering"],
        "seniority": ["C-Level"],
        "email_status": ["valid", "catch_all"],
        "title_keywords": ["cto"],
        "company_keywords": ["fintech"]
      }
    },
    "is_active": false,
    "match_threshold": 0.7,
    "created_at": "2026-07-22T21:28:40Z",
    "updated_at": "2026-07-22T21:28:41Z"
  },
  "credits_used": 0,
  "credits_remaining": 4005.0,
  "success": true
}
```

{% endtab %}

{% tab title="Error" %}

```json
{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "nl_text: Field required"
  },
  "success": false
}
```

{% endtab %}
{% endtabs %}