Dolead-Feedback-Loop-Documentation
Dolead Perf announcer API
General
| Parameter | Value |
|---|---|
| Root URL | https://api.dolead.com |
| Login | To be assigned by your account manager |
| Password | To be assigned by your account manager |
Limitations
Dolead conversions API will not process leads older than 60 days, and will not allow to push more than 1000 leads. Also, the API does not check the date format, nor any custom field in JSON format. Please make sure to send the fields well formatted as shared in the documentation so data could be parsed correctly.
Endpoint: Add announcer conversion information
Add multiple leads conversion data, for a specific client.
We track the following generic statuses for a lead:
- contacted : a prospective customer that has been contacted
- sale qualified lead : a prospective customer that has been researched and vetted - first by an organization’s marketing department and then by its sales team – and is deemed ready for the next stage
- sale : the prospect became a client, a sale was made
- turnover : turnover generate by lead
- sale failure reason : the reason of the sale failure
- contacted date : the date when you have managed to contact the lead
HTTP path
/lead_customer_conversion/add
Authentication
Use the header Basic Auth authorization with the login and password provided.
HTTP method
POST
Parameters (with “Content-Type: application/json”)
conversions: List of tuples[finder, setter]. Where finder and setter are dictionaries.
Finder parameter
The finder query should uniquely identify a lead.
Finder example (all possible fields):
{
'lead_id': 'dolead_lead_id_01', # Dolead lead ID
'customer_lead_id': 'customer_lead_id_01', # Announcer lead ID (if the value is stored by Dolead)
'phone_hash': '919c40429cceae8c34e100d135788b19fc1ca132b9ee2cdfa2755035ad9e948e' # SHA256 of user phone number, international format without the leading +
}
Ex: Given a French number “+33666666666”, phone_hash should be computed like sha256('33666666666').
You can use lead_id, customer_lead_id or phone_hash separately.
{
'lead_id': 'dolead_lead_id_01'
}
or
{
'customer_lead_id': 'customer_lead_id_01'
}
or
{
'phone_hash': '919c40429cceae8c34e100d135788b19fc1ca132b9ee2cdfa2755035ad9e948e'
}
Setter parameter
The setter dictionary contains the real payload (the real data to update), for a given lead.
You may have to translate your internal data to our current data model.
All the fields are optional. The more data our systems have, the more we can optimize our campaigns to lower your cost per sale.
We are mostly interested by customer_sale and customer_sql.
Setter example (all fields):
{
"customer_contacted": True,
"customer_contacted_at": "2011-03-21T00:18:56Z",
"customer_sql": True,
"customer_sale" : False,
"customer_sale_fail_reason": "invalid_number",
"customer_turnover": 59.14 # DECIMAL(5,2)
}
Setter standard fields list:
| arg | type |
|---|---|
| customer_contacted | Boolean |
| customer_contacted_at | Date ISO 8601 (2004) in UTC |
| customer_sale_fail_reason | String according to fail reasons list |
| customer_sale | Boolean |
| customer_turnover | Float, DECIMAL(5,2)String |
| customer_sql | Boolean |
Setter custom fields list:
| arg | type | description |
|---|---|---|
| call_center_id | String | ID of the Call center that treats the lead |
| call_center_name | String | Name Call center that treats the lead |
| credit_approved | Boolean | Credit approved |
| lead_status | String | Different Sales Funnel Stage Names / Funnel Length |
| sub_status | String | Detail about lead status (failure reason in case of failure) |
| net_sale | Boolean | Represents an advanced level of sale (flow is Contact → SQL → Sale → Net Sale) |
| product_type | String | Type of Product Sold |
| rep_id | String | Which dealer id the lead was forwarded/sold/assigned to |
| rep_name | String | Which dealer name the lead was forwarded/sold/assigned to |
| signed_contracts_count | Float | How many contracts signed / how many times sold per lead |
| date_calls | JSON | Payload to contain the timestamp of all calls: first call at, second call at,…last call at (see example below) |
| lead_imported_at | Date ISO 8601 (2004) in UTC | Date when the lead was imported at the customer CRM |
| custom_details | JSON | Payload to contain all custom details that can’t be sent in standarized fields (see examples below) |
Fail reasons
This is the list of acceptable fail reasons:
invalid_numberinvalid_emailunreachableno_projectproject_already_donewrong_categoryaccepted_another_offerrefused_offerother
For any custom failure reason not included in the list above, select other and send your custom value in the sub_status. The latter can also be used to add details for any failure reason already in the list (e.g. customer_sale_fail_reason= “refused_offer” ; sub_status=”Expensive Offer”)
Example (curl)
curl -g -XPOST "https://api.dolead.com/lead_customer_conversion/add" \
-H "Content-Type: application/json" \
-u LOGIN:PASSWORD \
-d '{"conversions":[
[
{
"lead_id": "dolead_lead_id_01"
},
{
"customer_contacted": true,
"customer_sale_fail_reason": "unreachable",
"customer_sql": true,
"customer_sale": false,
"date_calls" : {
"call_01": "2021-03-21T00:18:56Z",
"call_02": "2021-04-01T05:10:25Z",
"call_99": "2021-04-11T07:33:16Z"
},
"custom_details": {
"field_name1":"field_value1",
"field_name2":"field_value2",
"field_name3":["field_value_01", "field_value_02", "field_value_03"]
}
}
],
[
{
"lead_id": "dolead_lead_id_01"
},
{
"customer_contacted": true,
"customer_sale": true,
"customer_turnover": 59.14
}
]
]}'
Example (python)
import requests
LOGIN = "login"
PASSWORD = "password"
conversions = [
[
{
"lead_id": "dolead_lead_id_01"
},
{
"customer_contacted": True,
"customer_sale_fail_reason": "unreachable",
"customer_sql": True,
"customer_sale": False,
"date_calls" : {
"first_call": "2021-03-21T00:18:56Z",
"second_call": "2021-04-01T05:10:25Z",
"last_call": "2021-04-11T07:33:16Z"
},
"custom_details": {
"field_name1":"field_value1",
"field_name2":"field_value2",
"field_name3":["field_value_01", "field_value_02", "field_value_03"]
}
}
]
]
resp = requests.post('https://api.dolead.com/lead_customer_conversion/add',
json={'conversions': conversions},
auth=((LOGIN, PASSWORD)))
Returns
On success
If the request is well set and the payload is well formatted you will get an HTTP 200 response with the detail of execution. In success key, we provide the list of setter (depending on the setter used in your request) that have been well processed. In failure key, we provide the list of dict with setter key(s)/value(s) used, and the reason of failure in key error.
Case with only leads processed successfully
{
"result": "success",
"details": {
"success": [
{
"lead_id": "dolead_lead_id_01"
},
{
"lead_id": "dolead_lead_id_02"
}
],
"failure": []
}
}
Case with mix of leads processed successfully and with failures
{
"result": "success",
"details": {
"success": [
{
"lead_id": "dolead_lead_id_01"
}
],
"failure": [
{
"lead_id": "dolead_lead_id_02",
"error": "not existing"
}
]
}
}
Specific HTTP errors
Additionaly to HTTP standard errors, we can respond some specific errors depending of our endpoint API.
| status_code | error |
|---|---|
| 400 | conversions issue (ex: malformed payload, bad syntax) |
| 403 | authentification issue (ex: wrong login, password, auth header) |