Calculate Lead Score
Score a contact based on data completeness, opt-outs, and verification
Calculates a lead score for a contact based on custom field completion percentage (base score) minus deductions for opt-outs and missing verifications. Returns the score, a tier label, and a full breakdown of how the score was computed.
Requires a valid `api_key` and `developer_secret` in the JSON request body. Requests must originate from a whitelisted IP address.
Warning:
This endpoint uses `service_instance` (your user ID) instead of `api_key` for authentication. It also does not require `org_id`, `member_id`, or `brand_id`.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
service_instance |
body | string |
Yes | Your Zyntro user ID (not the API key). This is used internally to establish the database connection. |
developer_secret |
body | string |
Yes | Your developer secret (zdk_XXX). Issued during developer onboarding. |
contact_id |
body | string |
Yes | The UUID of the contact to score |
Score Tiers
| Tier | Score Range | What It Means |
|---|---|---|
| Excellent | 90 – 100 | High data quality, fully verified, no opt-outs. Priority lead. |
| Good | 70 – 89 | Strong profile with minor gaps. Likely a qualified lead. |
| Fair | 50 – 69 | Moderate data quality. Some custom fields missing or verification incomplete. |
| Poor | 30 – 49 | Significant data gaps or opt-outs reducing reachability. |
| Danger | 0 – 29 | Critical issues — heavy opt-outs, unverified contact methods, or sparse data. |
Score Deductions
| Condition | Deduction | Why It Matters |
|---|---|---|
| Email opt-out | -50 | Cannot reach the contact via email — the primary communication channel |
| SMS opt-out | -35 | Cannot send text messages to the contact |
| Do Not Call (DNC) | -25 | Cannot make phone calls to the contact |
| Email not verified (email exists) | -50 | Email may bounce, wasting send reputation |
| Phone not verified (phone exists) | -35 | Phone number may be invalid or disconnected |
Request Body
Content-Type: application/json
Example
json
{
"contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"developer_secret": "YOUR_DEVELOPER_SECRET",
"service_instance": "YOUR_USER_ID"
}Code Samples
bash
curl -X POST https://app.zyntrohq.com/apis/v2/public/crm/calculateLeadScore \
-H "Content-Type: application/json" \
-d '{
"service_instance": "YOUR_USER_ID",
"contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}'Response
200
Score calculated
json
{
"data": {
"raw_score": 65,
"base_score": 100,
"contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"deductions": {
"sms_optout": -35
},
"score_tier": "fair",
"display_score": 65,
"opt_out_status": {
"sms_optout": true,
"call_optout": false,
"email_optout": false
},
"total_deductions": -35,
"custom_fields_stats": {
"total": 8,
"filled": 6,
"completion_percentage": 75
},
"verification_status": {
"email_verified": true,
"phone_verified": false
}
},
"status": "success"
}
200
Error response
json
{
"data": [
"Contact not found"
],
"status": "error"
}Errors
| Code | Message | Resolution |
|---|---|---|
MISSING_SERVICE |
Missing service instance The `service_instance` field is missing. |
Include your user ID. |
MISSING_CONTACT |
Missing contact_id The `contact_id` field is missing. |
Provide the contact UUID. |
IP_NOT_WHITELISTED |
IP address not whitelisted The request originated from an IP not in the key's allowed list. |
Contact your client to add your IP to the developer key whitelist. |
INVALID_DEVELOPER_SECRET |
Invalid developer_secret The developer secret does not match any active key. |
Verify your developer secret. If lost, have your client revoke and reissue the key. |
MISSING_DEVELOPER_SECRET |
Missing developer_secret The `developer_secret` field is missing or empty. |
Include your developer secret in the request body. This is issued during developer onboarding. |
NOT_FOUND |
Contact not found No contact with that ID exists. |
Verify the contact_id. |
Tip:
The base score starts at 100 and is adjusted by custom field completion percentage. A contact with all 10 custom fields filled starts at 100; one with 7 out of 10 filled starts at 70. Deductions for opt-outs and missing verifications are then subtracted. The final score is clamped to a minimum of 0.
