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.

IP to Company (Smart Waterfall)

POST https://api.warmai.uk/functions/v1/ip-to-company

Identify the company behind a visitor IP address. Uses a smart hybrid waterfall that checks free local databases first (6.7M+ IP records, 2.4M VPN IPs, 434K hosting ranges), then fans out to paid providers only when needed.

Cost: 5 credits per business match. VPN, hosting, and ISP results are not charged.

Request Body

Field	Type	Required	Description
`ip`	string	Yes	IPv4 or IPv6 address

Response Fields

Field	Type	Description
`ip`	string	The IP address queried
`identified`	boolean	Whether a business was identified
`domain`	string	Company domain (if identified)
`company_name`	string	Company name (if available)
`confidence`	number	Confidence score (0–1)
`confidence_level`	string	`confirmed`, `likely`, or `unconfirmed`
`traffic_type`	string	`business`, `isp`, `hosting`, `vpn`, `education`, `government`, or `unknown`
`reason`	string	Why the result was classified this way
`matches`	array	All candidate matches ranked by confidence
`matches[].domain`	string	Candidate domain
`matches[].confidence`	number	Candidate confidence score
`vpn_provider`	string	VPN provider name (if detected)
`country_code`	string	ISO country code
`cached`	boolean	Whether this was a cached result (7-day TTL)

Example Request


curl -X POST "https://api.warmai.uk/functions/v1/ip-to-company" \
  -H "Content-Type: application/json" \
  -H "x-access-key: warm_YOUR_API_KEY" \
  -d '{"ip": "203.0.113.1"}'

Example Response (Business Match)


{
  "ip": "203.0.113.1",
  "identified": true,
  "domain": "example.com",
  "company_name": "Example Corp",
  "confidence": 0.85,
  "confidence_level": "confirmed",
  "traffic_type": "business",
  "reason": "Multiple providers agreed",
  "matches": [
    { "domain": "example.com", "confidence": 0.85 }
  ],
  "vpn_provider": null,
  "country_code": "US",
  "cached": false
}

Example Response (VPN Detected — Not Charged)


{
  "ip": "198.51.100.42",
  "identified": false,
  "domain": null,
  "company_name": null,
  "confidence": 0,
  "confidence_level": "unconfirmed",
  "traffic_type": "vpn",
  "reason": "VPN detected (NordVPN)",
  "matches": [],
  "vpn_provider": "NordVPN",
  "country_code": "NL",
  "cached": false
}

IP to Best Fit (Aggregate Lookup)

POST https://api.warmai.uk/functions/v1/ip-to-best-fit

Full company identification plus individual and decision maker enrichment. Runs the Smart Waterfall first — VPN, hosting, and ISP traffic is filtered at zero cost. Only unresolved IPs are sent for deeper enrichment.

Cost: 8 credits per lookup (VPN/hosting/ISP results are not charged).

Request Body

Field	Type	Required	Description
`ip_address`	string	Yes	IPv4 or IPv6 address
`website`	string	No	Your domain for contextual matching
`description`	string	No	Business description for better targeting

Response Fields

Field	Type	Description
`success`	boolean	Whether the request completed
`ip_address`	string	The IP address queried
`identified`	boolean	Whether a business was identified
`company`	string	Company name (if identified)
`domain`	string	Company domain (if identified)
`traffic_type`	string	`business`, `isp`, `hosting`, `vpn`, or `unknown`
`reason`	string	Why the result was classified this way
`confidence`	number	Confidence score (0–1)
`confidence_level`	string	`confirmed`, `likely`, or `unconfirmed`
`matches`	array	Candidate matches (business results only)

Example Request


curl -X POST "https://api.warmai.uk/functions/v1/ip-to-best-fit" \
  -H "Content-Type: application/json" \
  -H "x-access-key: warm_YOUR_API_KEY" \
  -d '{
    "ip_address": "203.0.113.1",
    "website": "yoursite.com",
    "description": "We sell B2B SaaS for marketing teams"
  }'

Example Response (ISP — Not Charged)


{
  "success": true,
  "ip_address": "81.246.16.178",
  "identified": false,
  "company": "Proximus",
  "domain": null,
  "traffic_type": "isp",
  "reason": "Residential/mobile ISP — cannot identify employer",
  "confidence": 1,
  "confidence_level": "confirmed"
}

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