Lead Scoring API

Description

This endpoint is used to score a lead based on provided information.

Authorization Mechanism

Authorization is done via an API key. For new customers, please reach out to [email protected]. For existing customers, please contact [email protected].

Request

Endpoint

https://api.leadcheck.ai/score-lead

Method

POST

Headers

• x-api-key
  • Required: True
  • Datatype: string
  • Value: Your API key provided at the time of sale
• Content-Type
  • Required: True
  • Datatype: string
  • Value: application/json

Body

• first_name
  • Required: True
  • Datatype: string
  • Value: Input first name. Full first name is required. Does not accept initial; must be at least 2 letters.
• last_name
  • Required: True
  • Datatype: string
  • Value: Input last name. Full last name is required. Does not accept initial; must be at least 2 letters.
• phone_number
  • Required: True
  • Datatype: string or integer
  • Value: Input US phone number. Formats accepted:
    • ###-###-####
    • ##########
    • 1##########
    • +1##########
    • +1(###)-###-####
    • (###)-###-####
    • ### ### ####

Examples

Python (Requests Library)

import json
import requests

api_endpoint = "https://api.leadcheck.ai/score-lead"
headers = {
    'x-api-key': 'your_api_key',
    'Content-Type': 'application/json'
}
payload = {
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+1-203-111-0099"
}
response = requests.post(api_endpoint, headers=headers, data=json.dumps(payload))
print(response.text)
    

Curl

curl -X POST \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -H "Host: api.leadcheck.ai" \
  -d '{"first_name":"John", "last_name":"Doe", "phone_number":"+1-203-111-0099"}' \
  https://api.leadcheck.ai/score-lead
    

Response

Successful Response

Status Code: 200

Status: success

Message: successfully scored

{
  "status": "success",
  "message": "successfully scored",
  "data": {
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1-203-111-0099",
    "is_mobile": true,
    "tier": "3",
    "propensity": 0.53855,
    "propensities": {
      "right_person_connected": 0.539,
      "wrong_person_connected": 0.405,
      "disconnected": 0.031
    }
  }
}
    

Error Responses

• 400: Invalid Request Body - Input data incorrectly.
• 401: Unauthorized - API key not authorized correctly.
• 403: Forbidden - API key is not active.
• 404: Not Found - Incorrect URL.
• 405: Method Not Allowed - Wrong method used to call API.
• 406: Not Acceptable - Response error.
• 413: Request Too Large - Request was too large.
• 415: Unsupported Media Type - Unsupported media type.
• 429: Too Many Requests - Exceeded rate or plan limit.
• 500: Internal Server Error - Unknown bug in service.
• 503: Service Unavailable - API is currently unavailable.

Data Descriptions

Request Parameters

• first_name: Input first name. (String)
• last_name: Input last name. (String)
• phone: Input phone number. (String)
• is_mobile: True if the input number is a mobile number. (Boolean)
• tier: Logical grouping of leads based on each tier's definition. (String)
  • Possible values: [1, 2, 3, 4, 5, invalid-input, invalid-phone, not-found]
• propensity: Output score for a lead's propensity to be a good lead. (Float, 0-1)
• propensities: Subset of propensities for the individual. (Dictionary)
  • right_person_connected: Propensity of a correct and connected number. (Float, 0-1)
  • wrong_person_connected: Propensity of an incorrect but connected number. (Float, 0-1)
  • disconnected: Propensity of a disconnected number. (Float, 0-1)

curl -X POST \
-H "x-api-key: {api_key}" \
-H "Content-Type: application/json" \
-d '{
        "first_name": "John",
        "last_name": "Doe",
        "phone_number": "{phone_number}"
}' \
https://api.leadcheck.ai/score-lead

{
    "status": "success",
    "message": "successfully scored",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": {phone_number},
        "is_mobile": true,
        "tier": "3",
        "propensity": 0.53855,
        "propensities": {
            "right_person_connected": 0.539,
            "wrong_person_connected": 0.405,
            "disconnected": 0.031
        }
    }
}
            

api_endpoint = "https://api.leadcheck.ai/score-lead"
phone_number = f"305{random.randint(1000000, 9999999)}"
headers = {
    'x-api-key': api_key,
    'Content-Type': 'application/json'
}
payload = {
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": phone_number
}
response = requests.post(api_endpoint, headers=headers, data=json.dumps(payload))
print(json.dumps(response.json(), indent=4))

{
    "status": "success",
    "message": "successfully scored",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": {phone_number},
        "is_mobile": false,
        "tier": "5",
        "propensity": 0.02217,
        "propensities": {
            "right_person_connected": 0.022,
            "wrong_person_connected": 0.052,
            "disconnected": 0.954
        }
    }
}
            

api_endpoint = "https://api.leadcheck.ai/score-lead"
phone_number = "333-333-3333"
headers = {
    'x-api-key': api_key,
    'Content-Type': 'application/json'
}
payload = {
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": phone_number
}
response = requests.post(api_endpoint, headers=headers, data=json.dumps(payload))
print(json.dumps(response.json(), indent=4))

{
    "status": "success",
    "message": "invalid-phone",
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": "333-333-3333",
        "is_mobile": null,
        "tier": "5",
        "propensity": 0,
        "propensities": {
            "right_person_connected": 0,
            "wrong_person_connected": 0,
            "disconnected": 1.0
        }
    }
}
            

api_endpoint = "https://api.leadcheck.ai/score-lead"
phone_number = "333-333-3333"
headers = {
    'x-api-key': api_key,
    'Content-Type': 'application/json'
}
payload = {
    "first_name": "John",
    "last_name": "D",
    "phone_number": phone_number
}
response = requests.post(api_endpoint, headers=headers, data=json.dumps(payload))
print(json.dumps(response.json(), indent=4))

{
    "status": "success",
    "message": "invalid input: last_name",
    "data": {
        "first_name": "John",
        "last_name": "D",
        "phone": "333-333-3333",
        "is_mobile": null,
        "tier": "invalid-input",
        "propensity": null,
        "propensities": {
            "right_person_connected": null,
            "wrong_person_connected": null,
            "disconnected": null
        }
    }
}
            

api_endpoint = "https://api.leadcheck.ai/score-lead"
phone_number = "333-333"
headers = {
    'x-api-key': api_key,
    'Content-Type': 'application/json'
}
payload = {
    "first_name": "John",
    "last_name": "D",
    "phone_number": phone_number
}
response = requests.post(api_endpoint, headers=headers, data=json.dumps(payload))
print(json.dumps(response.json(), indent=4))

{
    "status": "success",
    "message": "invalid input: last_namephone_number",
    "data": {
        "first_name": "John",
        "last_name": "D",
        "phone": "333-333",
        "is_mobile": null,
        "tier": "5",
        "propensity": 0,
        "propensities": {
            "right_person_connected": 0,
            "wrong_person_connected": 0,
            "disconnected": 1.0
        }
    }
}