Lead Scoring API
This document describes the input/output specifications for the three main Lead Scoring API endpoints.
Table of Contents
1. Webhook Endpoint
Endpoint
POST /api/v1/leadscoring/webhook
Description
Handles incoming webhook requests from Typeform for lead scoring v5 combined with v4 and v2. This endpoint processes form submissions, performs lead scoring analysis, and triggers Facebook CAPI events based on scoring thresholds.
Input
Request Body
The webhook expects a JSON payload with the following structure:
{
"event_type": "form_response",
"form_response": {
"answers": [
{
"field": {
"id": "string",
"type": "string"
},
"type": "choice|choices|multiple_choice|email|phone_number|text",
"choice": {
"label": "string"
},
"choices": {
"labels": ["string"]
},
"email": "string",
"phone_number": "string",
"text": "string"
}
],
"definition": {
"fields": [
{
"id": "string",
"title": "string"
}
]
},
"hidden": {
"client_id": "uuid",
"utm_source": "string",
"utm_campaign": "string",
"utm_medium": "string",
"utm_content": "string",
"utm_term": "string",
"first_name": "string",
"last_name": "string",
"phone_number": "string",
"email": "string",
"fbc": "string",
"fbp": "string",
"event_id": "string",
"consent_ip": "string"
},
"submitted_at": "2024-01-01T12:00:00Z"
}
}
Required Fields
event_type: Must be "form_response"form_response.hidden.client_id: Valid UUID for client identification- Form answers for: firstname, lastname, email, phone, consentdate, consentip
Optional Fields
- UTM parameters (utm_source, utm_campaign, utm_medium, utm_content, utm_term)
- Facebook tracking parameters (fbc, fbp, event_id)
- Form-specific questions and answers
Output
Success Response (200 OK)
{
"status_code": 200,
"data": "OK",
"message": null
}
Error Responses
400 Bad Request
{
"status_code": 400,
"message": "client_id is required"
}
404 Not Found
{
"status_code": 404,
"message": "Client not found"
}
500 Internal Server Error
{
"status_code": 500,
"message_code": "Internal Error",
"message": "Detailed error traceback"
}
Background Processing
The webhook triggers background processing that:
- Data Processing: Converts Typeform data to structured format
- External API Calls:
- Calls Pre-FI API for financial qualification
- Calls Form AI API for lead analysis
- Lead Scoring: Applies ML model to calculate probabilities
- Database Storage: Saves results to database
- Facebook CAPI: Conditionally fires conversion events
Example Request
curl -X POST "https://api.example.com/api/v1/leadscoring/webhook" \
-H "Content-Type: application/json" \
-d '{
"event_type": "form_response",
"form_response": {
"answers": [
{
"field": {"id": "name", "type": "short_text"},
"type": "text",
"text": "John Doe"
},
{
"field": {"id": "email", "type": "email"},
"type": "email",
"email": "[email protected]"
}
],
"hidden": {
"client_id": "123e4567-e89b-12d3-a456-426614174000",
"utm_source": "facebook",
"utm_campaign": "summer_sale",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+1234567890",
"consent_ip": "192.168.1.1"
},
"submitted_at": "2024-01-15T10:30:00Z"
}
}'
2. Get Lead Scoring Result
Endpoint
GET /api/v1/leadscoring?client_id={client_id}&email={email}
Description
Retrieves the lead scoring results for a specific email address and client.
Input
Query Parameters
client_id(required): UUID string identifying the clientemail(required): Email address of the lead
Example URL
GET /api/v1/leadscoring?client_id=123e4567-e89b-12d3-a456-426614174000&[email protected]
Output
Success Response (200 OK)
{
"status_code": 200,
"data": {
"email": "[email protected]",
"value": {
"p_fin": 0.75,
"p_show": 0.68,
"p_sql": 0.45,
"sal": "Yes",
"sal_rating": "Good",
"p_show_ai": 0.72,
"p_close_ai": 0.65,
"p_finq_ai": 0.80,
"p_intent_ai": 0.70,
"state_residence": "CA",
"rotator": "A"
},
"settings": {
"fb_capi_fin": 0.5,
"fb_capi_show": 0.6,
"a_rotator_fin": 0.7,
"a_rotator_show": 0.6,
"b_rotator_fin": 0.5,
"b_rotator_show": 0.5,
"c_rotator_fin": 0.3,
"c_rotator_show": 0.3,
"pixel_id": "123456789",
"event_name": "Lead",
"event_source_url": "https://example.com/form",
"action_source": "website"
}
},
"message": null
}
Field Descriptions
p_fin: Probability of financial qualification (0-1)p_show: Probability of showing up (0-1)p_sql: Probability of SQL (Sales Qualified Lead) (0-1)sal: Sales Accepted Lead status ("Yes"/"No")sal_rating: Financial rating ("Exceptional"/"Great"/"Good"/"Poor"/"Unknown")p_show_ai: AI-calculated show probability (0-1)p_close_ai: AI-calculated close probability (0-1)p_finq_ai: AI-calculated financial qualification probability (0-1)p_intent_ai: AI-calculated intent probability (0-1)state_residence: State of residencerotator: Rotator assignment ("A"/"B"/"C")
Not Found Response (404)
{
"status_code": 404,
"data": null,
"message": "Client not found"
}
No Data Response (200 OK)
{
"status_code": 200,
"data": null,
"message": null
}
Example Request
curl -X GET "https://api.example.com/api/v1/leadscoring?client_id=123e4567-e89b-12d3-a456-426614174000&[email protected]"
3. Fire Lead Scoring CAPI Event
Endpoint
POST /api/v1/leadscoring/fire-capi-event/{client_id}/{email}
Description
Manually triggers a Facebook Conversions API (CAPI) event for a specific lead based on their scoring results and configured thresholds.
Input
Path Parameters
client_id(required): UUID string identifying the clientemail(required): Email address of the lead
Example URL
POST /api/v1/leadscoring/fire-capi-event/123e4567-e89b-12d3-a456-426614174000/[email protected]
Output
Success Response (200 OK)
{
"status_code": 200,
"data": "success",
"message": null
}
Failed Threshold Response (200 OK)
{
"status_code": 200,
"data": "failed",
"message": null
}
Error Responses
404 Not Found
{
"status_code": 404,
"message": "Client not found"
}
404 Not Found (No Data)
{
"status_code": 404,
"message": "Client data not found"
}
500 Internal Server Error
{
"status_code": 500,
"message_code": "Error details",
"message": "Detailed error traceback"
}
CAPI Event Logic
The endpoint fires a Facebook CAPI event only when:
- Lead scoring data exists for the email
p_fin_model > fb_capi_finANDp_show_model > fb_capi_show- Valid Facebook access token and pixel ID are configured
Facebook CAPI Event Structure
When fired, the event includes:
{
"event_id": "mql{original_event_id}",
"event_name": "Lead",
"event_time": 1642248000,
"user_data": {
"emails": ["[email protected]"],
"phones": ["+1234567890"],
"first_name": "John",
"last_name": "Doe",
"fbc": "fb.1.1642248000.AbCdEfGhIjKlMnOp",
"fbp": "fb.1.1642248000.1234567890",
"client_ip_address": "192.168.1.1"
},
"event_source_url": "https://example.com/form",
"action_source": "website"
}
Example Request
curl -X POST "https://api.example.com/api/v1/leadscoring/fire-capi-event/123e4567-e89b-12d3-a456-426614174000/[email protected]"
Common Response Format
All endpoints follow a consistent response format:
{
"status_code": 200,
"data": "Response data or null",
"message": "Error message or null",
"message_code": "Error code or null"
}
Error Handling
HTTP Status Codes
200 OK: Successful request400 Bad Request: Invalid input parameters404 Not Found: Client or data not found500 Internal Server Error: Server-side error
Error Response Fields
status_code: HTTP status codemessage: Human-readable error messagemessage_code: Machine-readable error codedata: Always null for error responses
Authentication
All endpoints require proper authentication and authorization. The client_id parameter must correspond to a valid, authorized client in the system.
Rate Limiting
API endpoints are subject to rate limiting. Please refer to the API rate limiting documentation for specific limits and handling.
Support
For technical support or questions about these endpoints, please contact the development team or refer to the internal API documentation.