Built for GDPR teams: AI lead scoring for any CRM — no personal data storage.

TRY NOW

Product

Integrations

Pricing

Blog

Docs

BOOK A DEMO

API

Scoring API Reference

Overview

The Conturs Scoring API calculates lead quality scores based on configurable weights.

Property	Value
Base URL	https://api.conturs.com
Protocol	HTTP / JSON
Auth	API Key in request body
Content-Type	`application/json`

Authentication

Every request to POST /leads must include api_key and email in the JSON body.

Get your API key from Dashboard → API at conturs.com.

{
  "api_key": "ck_live_abc123...",
  "email": "you@company.com"
}

{
  "api_key": "ck_live_abc123...",
  "email": "you@company.com"
}

{
  "api_key": "ck_live_abc123...",
  "email": "you@company.com"
}

Endpoints

GET /health

Returns the service health status. No authentication required.

Response 200 OK

{
  "status": "healthy",
  "service": "scoring-service"
}

{
  "status": "healthy",
  "service": "scoring-service"
}

{
  "status": "healthy",
  "service": "scoring-service"
}

Field	Type	Description
`status`	string	Always "healthy"
`service`	string	Always "scoring-service"

POST /leads

Score a batch of leads against your personalized ICP model. Send one or more leads and receive a score (0–100) with a full factor breakdown for each.

Request Body

Field	Type	Required	Description
`api_key`	string	Yes	Your Conturs API key
`email`	string	Yes	Your account email
`leads`	Lead[]	Yes	Array of lead objects (min 1)
`client_id`	string	No	Optional client identifier override

Lead Object

Field	Type	Required	Example	Description
`email`	string	Yes	`"john@acme.com"`	Lead email address. Used as identifier.
`firstname`	string	No	`"John"`	First name. Contributes to profile completeness.
`lastname`	string	No	`"Doe"`	Last name. Contributes to profile completeness.
`company`	string	No	`"Acme Corp"`	Company name. Contributes to profile completeness.
`jobtitle`	string	No	`"VP of Sales"`	Job title. Evaluated for seniority level.
`industry`	string	No	`"Technology"`	Company industry.
`phone`	string	No	`"+1234567890"`	Phone number. Presence adds to score.
`lead_status`	string	No	`"qualified"`	Pipeline status. See values below.
`dealstage`	string	No	`"presentationscheduled"`	Deal stage. See values below.
`amount`	number	No	`50000`	Deal value in USD. Scored up to $100k.
`num_meetings_booked`	integer	No	`2`	Number of meetings booked.
`num_calls`	integer	No	`3`	Number of calls completed.
`hs_email_replied`	integer	No	`2`	Number of email replies received.
`num_completed_tasks`	integer	No	`4`	Number of completed tasks.
`hs_last_sales_activity_timestamp`	string	No	`"2026-02-20T10:30:00Z"`	Last activity date. ISO 8601 or Unix ms.
`create_date`	string	No	`"2026-01-15"`	Lead creation date. ISO 8601 or Unix ms.

Lead Status Values

Value	Factor Score
`qualified`	1.0
`in_progress`	0.7
`open`	0.5
`new`	0.3
`bad_timing`	0.2
`unqualified`	0.1
other	0.3
empty	0.2

Deal Stage Values

Value	Factor Score
`closedwon`	1.0
`contractsent`	0.85
`decisionmakerboughtin`	0.75
`presentationscheduled`	0.6
`qualifiedtobuy`	0.5
`appointmentscheduled`	0.4
`closedlost`	0.1
other	0.2
empty	0.0

Job Title Seniority Mapping

Keywords in title	Factor Score
ceo, founder, owner, president, chief	1.0
vp, director	0.8
head, manager, lead	0.6
senior, sr	0.4
other title	0.3
no title	0.0

Response 200 OK

Field	Type	Description
`scores`	LeadScore[]	Array of scored leads
`method`	string	Weight source: similar_clients, industry_prior, or default
`client_id`	string	Your client identifier from config

LeadScore Object

Field	Type	Description
`email`	string	Lead identifier (matches request)
`score`	integer	Score 0–100
`label`	string	Human-readable label
`factors`	Factor[]	Breakdown of scoring factors

Factor Object

Field	Type	Description
`name`	string	Factor name (e.g. deal_stage, job_title_seniority)
`weight`	float	How important this factor is (from config)
`value`	float	Lead's normalized value (0.0–1.0)
`contribution`	float	value x weight — actual contribution

Score Labels

Range	Label	Recommended Action
80–100	Hot Lead	Route to AE immediately
60–79	Warm Lead	SDR outreach sequence
40–59	Cool Lead	Nurture if signals positive
0–39	Cold Lead	Marketing drip only

All 13 Scoring Factors

Each lead is evaluated across 13 factors. Weights are personalized for your business.

#	Factor	What it measures	Score logic
1	`deal_stage`	Current deal stage	Mapped value (see table above)
2	`deal_amount`	Deal value	min(1.0, amount/100000 + 0.3)
3	`lead_status`	Pipeline status	Mapped value (see table above)
4	`days_since_last_activity`	Recency of sales activity	3d: 1.0, 7d: 0.8, 14d: 0.6, 30d: 0.4, 60d: 0.2, 60d+: 0.05
5	`meeting_booked_count`	Meetings booked	3+: 1.0, 1+: 0.7, 0: 0.0
6	`call_completed_count`	Calls completed	5+: 1.0, 2+: 0.6, 1: 0.4, 0: 0.0
7	`email_reply_count`	Email replies	5+: 1.0, 2+: 0.7, 1: 0.5, 0: 0.0
8	`tasks_completed_count`	Tasks completed	min(1.0, count/5)
9	`days_since_create`	Lead freshness	7d: 1.0, 30d: 0.7, 90d: 0.4, 90d+: 0.2
10	`job_title_seniority`	Job title seniority	Keyword matching (see table above)
11	`has_email_valid`	Valid email	Has @: 1.0, Invalid: 0.0
12	`profile_completeness`	Data completeness	Filled fields / 7
13	`has_phone`	Has phone number	Present: 1.0, Empty: 0.0

Score Calculation Formula

1. For each factor: contribution = value x weight

2. Normalize: normalized = total_contributions / total_weights_used

3. Completeness multiplier: 0.5 + 0.5 x (weights_used / weights_available)

4. Final: score = clamp(normalized x multiplier x 100, 0, 100) rounded to integer

Examples

Minimal Request

curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [
      {
        "email": "jane@startup.io"
      }
    ]
  }'

curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [
      {
        "email": "jane@startup.io"
      }
    ]
  }'

curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [
      {
        "email": "jane@startup.io"
      }
    ]
  }'

Full Request

curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [
      {
        "email": "john.doe@acme.com",
        "firstname": "John",
        "lastname": "Doe",
        "company": "Acme Corp",
        "jobtitle": "VP of Sales",
        "industry": "Technology",
        "phone": "+1234567890",
        "lead_status": "qualified",
        "dealstage": "presentationscheduled",
        "amount": 50000,
        "num_meetings_booked": 2,
        "num_calls": 3,
        "hs_email_replied": 2,
        "num_completed_tasks": 4,
        "hs_last_sales_activity_timestamp": "2026-02-20T10:30:00Z",
        "create_date": "2026-02-01"
      }
    ]
  }'

curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [
      {
        "email": "john.doe@acme.com",
        "firstname": "John",
        "lastname": "Doe",
        "company": "Acme Corp",
        "jobtitle": "VP of Sales",
        "industry": "Technology",
        "phone": "+1234567890",
        "lead_status": "qualified",
        "dealstage": "presentationscheduled",
        "amount": 50000,
        "num_meetings_booked": 2,
        "num_calls": 3,
        "hs_email_replied": 2,
        "num_completed_tasks": 4,
        "hs_last_sales_activity_timestamp": "2026-02-20T10:30:00Z",
        "create_date": "2026-02-01"
      }
    ]
  }'

curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [
      {
        "email": "john.doe@acme.com",
        "firstname": "John",
        "lastname": "Doe",
        "company": "Acme Corp",
        "jobtitle": "VP of Sales",
        "industry": "Technology",
        "phone": "+1234567890",
        "lead_status": "qualified",
        "dealstage": "presentationscheduled",
        "amount": 50000,
        "num_meetings_booked": 2,
        "num_calls": 3,
        "hs_email_replied": 2,
        "num_completed_tasks": 4,
        "hs_last_sales_activity_timestamp": "2026-02-20T10:30:00Z",
        "create_date": "2026-02-01"
      }
    ]
  }'

Full Response

{
  "scores": [
    {
      "email": "john.doe@acme.com",
      "score": 85,
      "label": "Hot Lead",
      "factors": [
        { "name": "deal_stage", "weight": 0.15, "value": 0.6, "contribution": 0.09 },
        { "name": "deal_amount", "weight": 0.10, "value": 0.80, "contribution": 0.08 },
        { "name": "lead_status", "weight": 0.10, "value": 1.0, "contribution": 0.10 },
        { "name": "job_title_seniority", "weight": 0.10, "value": 0.8, "contribution": 0.08 },
        { "name": "meeting_booked_count", "weight": 0.08, "value": 0.7, "contribution": 0.056 },
        { "name": "call_completed_count", "weight": 0.07, "value": 0.6, "contribution": 0.042 },
        { "name": "email_reply_count", "weight": 0.07, "value": 0.7, "contribution": 0.049 },
        { "name": "tasks_completed_count", "weight": 0.05, "value": 0.8, "contribution": 0.04 },
        { "name": "days_since_last_activity", "weight": 0.08, "value": 1.0, "contribution": 0.08 },
        { "name": "days_since_create", "weight": 0.05, "value": 0.7, "contribution": 0.035 },
        { "name": "has_email_valid", "weight": 0.05, "value": 1.0, "contribution": 0.05 },
        { "name": "profile_completeness", "weight": 0.05, "value": 1.0, "contribution": 0.05 },
        { "name": "has_phone", "weight": 0.05, "value": 1.0, "contribution": 0.05 }
      ]
    }
  ],
  "method": "similar_clients",
  "client_id": "client-abc123"
}

{
  "scores": [
    {
      "email": "john.doe@acme.com",
      "score": 85,
      "label": "Hot Lead",
      "factors": [
        { "name": "deal_stage", "weight": 0.15, "value": 0.6, "contribution": 0.09 },
        { "name": "deal_amount", "weight": 0.10, "value": 0.80, "contribution": 0.08 },
        { "name": "lead_status", "weight": 0.10, "value": 1.0, "contribution": 0.10 },
        { "name": "job_title_seniority", "weight": 0.10, "value": 0.8, "contribution": 0.08 },
        { "name": "meeting_booked_count", "weight": 0.08, "value": 0.7, "contribution": 0.056 },
        { "name": "call_completed_count", "weight": 0.07, "value": 0.6, "contribution": 0.042 },
        { "name": "email_reply_count", "weight": 0.07, "value": 0.7, "contribution": 0.049 },
        { "name": "tasks_completed_count", "weight": 0.05, "value": 0.8, "contribution": 0.04 },
        { "name": "days_since_last_activity", "weight": 0.08, "value": 1.0, "contribution": 0.08 },
        { "name": "days_since_create", "weight": 0.05, "value": 0.7, "contribution": 0.035 },
        { "name": "has_email_valid", "weight": 0.05, "value": 1.0, "contribution": 0.05 },
        { "name": "profile_completeness", "weight": 0.05, "value": 1.0, "contribution": 0.05 },
        { "name": "has_phone", "weight": 0.05, "value": 1.0, "contribution": 0.05 }
      ]
    }
  ],
  "method": "similar_clients",
  "client_id": "client-abc123"
}

{
  "scores": [
    {
      "email": "john.doe@acme.com",
      "score": 85,
      "label": "Hot Lead",
      "factors": [
        { "name": "deal_stage", "weight": 0.15, "value": 0.6, "contribution": 0.09 },
        { "name": "deal_amount", "weight": 0.10, "value": 0.80, "contribution": 0.08 },
        { "name": "lead_status", "weight": 0.10, "value": 1.0, "contribution": 0.10 },
        { "name": "job_title_seniority", "weight": 0.10, "value": 0.8, "contribution": 0.08 },
        { "name": "meeting_booked_count", "weight": 0.08, "value": 0.7, "contribution": 0.056 },
        { "name": "call_completed_count", "weight": 0.07, "value": 0.6, "contribution": 0.042 },
        { "name": "email_reply_count", "weight": 0.07, "value": 0.7, "contribution": 0.049 },
        { "name": "tasks_completed_count", "weight": 0.05, "value": 0.8, "contribution": 0.04 },
        { "name": "days_since_last_activity", "weight": 0.08, "value": 1.0, "contribution": 0.08 },
        { "name": "days_since_create", "weight": 0.05, "value": 0.7, "contribution": 0.035 },
        { "name": "has_email_valid", "weight": 0.05, "value": 1.0, "contribution": 0.05 },
        { "name": "profile_completeness", "weight": 0.05, "value": 1.0, "contribution": 0.05 },
        { "name": "has_phone", "weight": 0.05, "value": 1.0, "contribution": 0.05 }
      ]
    }
  ],
  "method": "similar_clients",
  "client_id": "client-abc123"
}

Error Responses

Status	Error Message	Cause
400	Invalid request body: {details}	Malformed JSON in request
400	No leads provided	Empty leads array
401	api_key and email required	Missing api_key or email field
401	Invalid API key	API key rejected
405	Method not allowed	Non-POST request to /leads
500	Failed to fetch scoring config	Config API unavailable

{
  "error": "api_key and email required"
}

{
  "error": "api_key and email required"
}

{
  "error": "api_key and email required"
}

Date Format Support

Format	Example
Unix milliseconds	"1645564800000"
RFC 3339 / ISO 8601	"2026-02-22T12:00:00Z"
Date only (dash)	"2026-02-22"
Date only (slash)	"2026/02/22"

SDK Examples

Python

import requests

response = requests.post("https://api.conturs.com/leads", json={
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [{
        "email": "jane@startup.io",
        "company": "Startup Inc",
        "jobtitle": "CEO",
        "lead_status": "qualified",
        "amount": 30000
    }]
})

data = response.json()
for lead in data["scores"]:
    print(f"{lead['email']}: {lead['score']} ({lead['label']})")

import requests

response = requests.post("https://api.conturs.com/leads", json={
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [{
        "email": "jane@startup.io",
        "company": "Startup Inc",
        "jobtitle": "CEO",
        "lead_status": "qualified",
        "amount": 30000
    }]
})

data = response.json()
for lead in data["scores"]:
    print(f"{lead['email']}: {lead['score']} ({lead['label']})")

import requests

response = requests.post("https://api.conturs.com/leads", json={
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [{
        "email": "jane@startup.io",
        "company": "Startup Inc",
        "jobtitle": "CEO",
        "lead_status": "qualified",
        "amount": 30000
    }]
})

data = response.json()
for lead in data["scores"]:
    print(f"{lead['email']}: {lead['score']} ({lead['label']})")

JavaScript (Node.js)

const response = await fetch("https://api.conturs.com/leads", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "ck_live_abc123",
    email: "you@company.com",
    leads: [{
      email: "jane@startup.io",
      company: "Startup Inc",
      jobtitle: "CEO",
      lead_status: "qualified",
      amount: 30000
    }]
  })
});

const data = await response.json();
data.scores.forEach(lead => {
  console.log(`${lead.email}: ${lead.score} (${lead.label})`);
});

const response = await fetch("https://api.conturs.com/leads", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "ck_live_abc123",
    email: "you@company.com",
    leads: [{
      email: "jane@startup.io",
      company: "Startup Inc",
      jobtitle: "CEO",
      lead_status: "qualified",
      amount: 30000
    }]
  })
});

const data = await response.json();
data.scores.forEach(lead => {
  console.log(`${lead.email}: ${lead.score} (${lead.label})`);
});

const response = await fetch("https://api.conturs.com/leads", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "ck_live_abc123",
    email: "you@company.com",
    leads: [{
      email: "jane@startup.io",
      company: "Startup Inc",
      jobtitle: "CEO",
      lead_status: "qualified",
      amount: 30000
    }]
  })
});

const data = await response.json();
data.scores.forEach(lead => {
  console.log(`${lead.email}: ${lead.score} (${lead.label})`);
});

cURL

# Health check
curl https://api.conturs.com/health

# Score leads
curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [{"email": "test@example.com"}]
  }'

# Health check
curl https://api.conturs.com/health

# Score leads
curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [{"email": "test@example.com"}]
  }'

# Health check
curl https://api.conturs.com/health

# Score leads
curl -X POST https://api.conturs.com/leads \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ck_live_abc123",
    "email": "you@company.com",
    "leads": [{"email": "test@example.com"}]
  }'