Visitors API

Retrieve identified website visitors with their profile data and ICP scores.

Required Headers

Header	Description
`x-access-key`	Your Warm AI API key

Identification Types

Warm AI supports two identification types depending on the visitor’s region.

Individual (US)

Personal identification via IP lookup with LinkedIn profile data. Returns the visitor’s name, job title, company, and LinkedIn URL.

Company (EU)

GDPR-compliant identification at the company level. Returns company name, industry, employee count, and location without exposing personal data.

List Identifications

GET https://api.warmai.uk/identification-list

Retrieve identified visitors for a given website.

Query Parameters

Parameter	Type	Required	Description
`website_id`	string	Yes	The website ID to retrieve visitors for
`status`	string	No	Filter by status: `pending`, `identified`, `failed`
`type`	string	No	Filter by identification type: `individual`, `company`
`qualified`	boolean	No	Filter by ICP qualification: `true` or `false`
`limit`	integer	No	Number of results to return (default `100`, max `500`)
`offset`	integer	No	Number of results to skip for pagination

Response Fields

Field	Type	Description
`identifications`	array	List of identification objects
`identifications[].id`	string	Unique identification ID
`identifications[].identification_type`	string	`individual` or `company`
`identifications[].status`	string	`pending`, `identified`, or `failed`
`identifications[].identified_at`	string	ISO 8601 timestamp
`identifications[].individual`	object	Present for `individual` type identifications
`identifications[].individual.linkedin_url`	string	LinkedIn profile URL
`identifications[].individual.linkedin_name`	string	Full name from LinkedIn
`identifications[].individual.linkedin_title`	string	Job title
`identifications[].individual.linkedin_company`	string	Company name
`identifications[].company`	object	Present for `company` type identifications
`identifications[].company.name`	string	Company name
`identifications[].company.domain`	string	Company website domain
`identifications[].company.industry`	string	Industry sector
`identifications[].company.employee_count`	string	Employee count range
`identifications[].company.location`	string	Company headquarters location
`identifications[].company.linkedin_url`	string	Company LinkedIn page URL
`identifications[].icp_scores`	array	ICP scoring results
`identifications[].icp_scores[].icp_id`	string	The ICP ID
`identifications[].icp_scores[].icp_name`	string	The ICP name
`identifications[].icp_scores[].score`	number	Match score (0-100)
`identifications[].icp_scores[].qualified`	boolean	Whether the visitor meets the ICP threshold
`identifications[].icp_scores[].ai_summary`	string	AI-generated summary of the match
`identifications[].session`	object	Visitor session data
`identifications[].session.pages_visited`	integer	Number of pages viewed
`identifications[].session.duration_seconds`	integer	Session duration in seconds
`identifications[].session.referrer`	string	Referring URL

Example Request


curl -X GET "https://api.warmai.uk/identification-list?website_id=ws_a1b2c3d4&status=identified&limit=10" \
  -H "x-access-key: YOUR_API_KEY"

Example Response


{
  "identifications": [
    {
      "id": "ident_001",
      "identification_type": "individual",
      "status": "identified",
      "identified_at": "2026-03-19T14:22:00Z",
      "individual": {
        "linkedin_url": "https://linkedin.com/in/janedoe",
        "linkedin_name": "Jane Doe",
        "linkedin_title": "VP of Marketing",
        "linkedin_company": "Acme Corp"
      },
      "company": null,
      "icp_scores": [
        {
          "icp_id": "icp_abc123",
          "icp_name": "Marketing Leaders",
          "score": 87,
          "qualified": true,
          "ai_summary": "Strong match - VP-level marketing role at a mid-market SaaS company with 200+ employees."
        }
      ],
      "session": {
        "pages_visited": 5,
        "duration_seconds": 240,
        "referrer": "https://google.com"
      }
    },
    {
      "id": "ident_002",
      "identification_type": "company",
      "status": "identified",
      "identified_at": "2026-03-19T13:10:00Z",
      "individual": null,
      "company": {
        "name": "TechStart GmbH",
        "domain": "techstart.de",
        "industry": "Software Development",
        "employee_count": "51-200",
        "location": "Berlin, Germany",
        "linkedin_url": "https://linkedin.com/company/techstart-gmbh"
      },
      "icp_scores": [
        {
          "icp_id": "icp_abc123",
          "icp_name": "Marketing Leaders",
          "score": 62,
          "qualified": false,
          "ai_summary": "Partial match - correct industry but company size is below the target range."
        }
      ],
      "session": {
        "pages_visited": 3,
        "duration_seconds": 120,
        "referrer": "https://linkedin.com"
      }
    }
  ]
}