ICPs API

Create and manage Ideal Customer Profiles with AI-powered generation.

Required Headers

Header	Description
`x-access-key`	Your Warm AI API key
`x-idempotency-key`	Unique key to prevent duplicate requests
`x-user-id`	Your Warm AI user ID
`Content-Type`	`application/json`

AI-Powered Generation

All fields except product_id are optional. When you create an ICP, Warm AI’s AI engine generates the profile from your linked product data. ICPs start in "generating" status while the AI builds the profile. Review the generated ICP before activating it.

ICP Limits by Plan

Plan	Max ICPs
Free	1
Basic	5
Standard	10
Pro	25
Team	100

Endpoints

Create ICP

POST https://api.warmai.uk/api-icp-action

Create a new Ideal Customer Profile. The AI will generate missing fields from your linked product.

Request Body

Field	Type	Required	Description
`action`	string	Yes	Must be `"create_icp"`
`product_id`	string	Yes	The product ID to generate the ICP from
`name`	string	No	Display name for the ICP
`description`	string	No	Description of the ideal customer
`job_titles`	string[]	No	Target job titles (e.g. `["VP of Marketing", "CMO"]`)
`pain_points`	string[]	No	Pain points the product solves
`value_drivers`	string[]	No	Key value propositions for this audience
`industry_focus`	string[]	No	Target industries
`company_characteristics`	object	No	Target company attributes (size, revenue, etc.)

Example Request


{
  "action": "create_icp",
  "product_id": "prod_xyz789",
  "name": "Enterprise Marketing Leaders",
  "job_titles": ["VP of Marketing", "CMO", "Head of Growth"],
  "industry_focus": ["SaaS", "FinTech"]
}

Response Fields

Field	Type	Description
`id`	string	Unique ICP ID
`name`	string	ICP display name
`description`	string	AI-generated or user-provided description
`product_id`	string	Linked product ID
`job_titles`	string[]	Target job titles
`pain_points`	string[]	Identified pain points
`value_drivers`	string[]	Key value propositions
`industry_focus`	string[]	Target industries
`company_characteristics`	object	Target company attributes
`workflow_status`	string	`generating`, `generated`, `active`, `paused`
`review_status`	string	`pending_review`, `approved`, `rejected`
`created_at`	string	ISO 8601 timestamp

Example Response


{
  "id": "icp_abc123",
  "name": "Enterprise Marketing Leaders",
  "description": "Senior marketing decision-makers at mid-to-large SaaS and FinTech companies looking to scale outbound pipeline.",
  "product_id": "prod_xyz789",
  "job_titles": ["VP of Marketing", "CMO", "Head of Growth"],
  "pain_points": [
    "Low reply rates on cold outreach",
    "Difficulty identifying high-intent prospects",
    "Manual prospect research is time-consuming"
  ],
  "value_drivers": [
    "AI-powered visitor identification",
    "Automated ICP scoring",
    "Personalized outreach at scale"
  ],
  "industry_focus": ["SaaS", "FinTech"],
  "company_characteristics": {
    "employee_count": "200-5000",
    "revenue_range": "$10M-$500M"
  },
  "workflow_status": "generating",
  "review_status": "pending_review",
  "created_at": "2026-03-19T12:00:00Z"
}

List ICPs

POST https://api.warmai.uk/api-icp-action

Retrieve all ICPs for your account.

Request Body

Field	Type	Required	Description
`action`	string	Yes	Must be `"list_icps"`

Example Request


{
  "action": "list_icps"
}

Response Fields

Field	Type	Description
`data`	array	List of ICP objects (same fields as Create ICP response)

Example Response


{
  "data": [
    {
      "id": "icp_abc123",
      "name": "Enterprise Marketing Leaders",
      "description": "Senior marketing decision-makers at mid-to-large SaaS and FinTech companies.",
      "product_id": "prod_xyz789",
      "job_titles": ["VP of Marketing", "CMO", "Head of Growth"],
      "pain_points": [
        "Low reply rates on cold outreach",
        "Difficulty identifying high-intent prospects"
      ],
      "value_drivers": [
        "AI-powered visitor identification",
        "Automated ICP scoring"
      ],
      "industry_focus": ["SaaS", "FinTech"],
      "company_characteristics": {
        "employee_count": "200-5000",
        "revenue_range": "$10M-$500M"
      },
      "workflow_status": "active",
      "review_status": "approved",
      "created_at": "2026-03-19T12:00:00Z"
    }
  ]
}