API Reference

Learn how to set up Conturs and start scoring leads in minutes.

Overview

The Conturs Scoring Service is a lightweight Go microservice that scores leads locally on your infrastructure. It fetches personalized scoring weights from the Config API and calculates scores with microsecond latency. Your lead data never leaves your servers.

Scoring Service: Self-hosted, runs on localhost:8082

Config API: api.conturs.com (provides personalized weights)

Quick Start

# Download and run
go build -o scoring main.go
./scoring

# Service starts on http://localhost:8082

Source code: github.com/conturs-team/scoring

Authentication

Every API request includes your api_key and email in the request body. Get your API key from Dashboard → API at conturs.com.

Health Check

GET /health

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

Score Leads

POST /leads

Score a batch of leads against your personalized ICP model. The service fetches weights from the Config API on the first call, then caches them locally.

Request Body

{
  "api_key": "your-api-key",
  "email": "you@company.com",
  "leads": [
    {
      "email": "john@acme.com",
      "first_name": "John",
      "last_name": "Smith",
      "phone": "+1-555-0100",
      "company": "Acme Corp",
      "job_title": "VP Sales",
      "city": "San Francisco",
      "country": "US",
      "industry": "B2B SaaS",
      "email_open_count": 5,
      "email_click_count": 2,
      "lead_status": "qualified",
      "num_deals": 1,
      "deal_amount": 25000,
      "create_date": "2026-01-15",
      "notes_last_updated": "2026-02-01"
    }
  ]
}

Required Fields

api_key (string) — Your Conturs API key
email (string) — Your account email
leads (array) — Array of lead objects to score

Lead Object Fields

email (string) — Lead's email address
first_name, last_name (string) — Contact name
phone (string) — Phone number
company (string) — Company name
job_title (string) — Job title
city, country (string) — Location
industry (string) — Company industry
email_open_count, email_click_count (number) — Engagement metrics
lead_status (string) — One of: new, open, in_progress, qualified, unqualified
num_deals (number) — Number of associated deals
deal_amount (number) — Total deal value
create_date (string) — When the lead was created
notes_last_updated (string) — Last activity date

Response

{
  "scores": [
    {
      "email": "john@acme.com",
      "score": 87,
      "label": "Hot Lead",
      "factors": [
        {
          "name": "Company Match",
          "weight": 0.15,
          "value": 1.0,
          "contribution": 0.15
        },
        {
          "name": "Industry Match",
          "weight": 0.12,
          "value": 1.0,
          "contribution": 0.12
        },
        {
          "name": "Engagement",
          "weight": 0.10,
          "value": 0.8,
          "contribution": 0.08
        }
      ]
    }
  ],
  "method": "similar_clients",
  "client_id": "abc123"
}

Response Fields

scores (array) — Array of scored leads
scores[].email (string) — Lead identifier
scores[].score (integer, 0–100) — Overall similarity score
scores[].label (string) — Human-readable label: Hot Lead (80–100), Warm Lead (60–79), Cool Lead (40–59), Cold Lead (0–39)
scores[].factors (array) — Individual scoring factors with weight, value, and contribution
method (string) — Weight source: similar_clients (personalized), industry_prior (industry benchmark), default (baseline)
client_id (string) — Your client identifier

Scoring Factors

Each lead is evaluated across 10 factors. Weights are personalized based on what works for similar businesses.

Lead Source — Whether the lead has a valid email source
Valid Email — Email format validation
Company Match — Company name present and matchable
Industry Match — Industry alignment with your ICP
Recency — How recently the lead was created
Lead Status — Current pipeline status (qualified > in_progress > open > new)
Engagement — Email opens and clicks activity
Profile Completeness — How many data fields are filled
Company Size — Employee count alignment with your ICP
Activity Recency — How recently notes or data were updated

Score Calculation

Scores are calculated as: score = Σ(factor_value × factor_weight) × 100

Each factor contributes proportionally based on its personalized weight. Weights are generated by the Config API based on conversion patterns of similar businesses.