Create ICP

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

Create ICP

POST /create_icp

Free — no credits are charged. Every response still returns credits_used and credits_remaining.

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.

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.

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 for the fields every endpoint returns.

Example

Input

{
  "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
}

Output

{
  "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
}

Error

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