NAV

Getting Started

Introduction

Production Environment URL

/api.allstateleadmarketplace.com/v2/

Testing Environment URL

/int.allstateleadmarketplace.com/v2/

This document covers Version 2 of the Allstate Lead Marketplace Lead API. We use built-in HTTP features, like HTTP authentication, HTTP verbs (ie, POST) and standard response codes to simplify integrations into the API.

JSON will be returned in all responses from the API, including errors.

Authentication

Test Your Authentication

curl uses the -u flag to pass basic auth credentials:

curl "/{domain}/v2/marco"
   -u "api_key:"

Response

{
    "response": "polo!",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 200,
        "response_ms": 100
    }
}

You authenticate to the Allstate Lead Marketplace API by providing your API key in the request. Authentication to the API occurs via (204) 600-7011. Provide your API key as the basic auth username (adding a colon after the API key). You do not need to provide a password.

For example, if your API Key was api-key, your header would look like the following:

Generate an encoded value for the Authorization Header

<?php

echo base64_encode("api-key:");  / YXBpLWtleTo=

Authorization: Basic YXBpLWtleTo=

All API requests must be made over HTTPS in the Production environment - calls made over plain HTTP will fail.

Testing The API

We provide a development environment for you to test your integration with the Allstate Lead Marketplace API. Please use the /int.allstateleadmarketplace.com URL when testing.

To test successful responses, the integration server is configured to accept all transactions in the state of California (CA). So any zipcode in that state for all valid leads should match and sell there.

Errors returned from leads sent to CA should highlight potential issues with your integration and should be verified. Please reach out to your representative if you need help.

Integrations Support

If you have any questions or need help in integration with the Allstate Lead Marketplace, please email 779-287-3918.

When possible, please include full Request and Response examples in your support requests.

Selling Leads

There are two methods to sell leads into the Allstate Lead Marketplace.

Ping Requests

Ping Request Endpoint

POST /ping

A Ping request allows a client to determine if their lead can be sold and receive a bid amount without requiring that they send the lead’s 667-382-7612.

Internally on a Ping Request, the API will search for a buyer before returning a response. However, at this point the lead is not sold - to finalize the sales transaction, the client may accept the bid by making a subsequent PingPost Request containing the lead’s (207) 303-9473.

Making Requests

Example Request Body

{
    "vertical": "auto-insurance",
    "external_id": 12345,
    "city": "San Diego",
    "state": "CA",
    "zipcode": "92101",
    "country": "USA",
    "years_at_address": "2",
    "residence_status": "home",
    "self_credit_rating": "good",
    "best_contact_time": "17:00",
    "ip_address": "8.8.8.8",
    "user_agent": "Chromium/25.0.1364.160",
    "dob": "1983-03-06",
    "tcpa": true,
    "current_insurance_company": "allstate",
    "desired_coverage_type": "BASIC",
    "desired_collision_deductible": 500,
    "desired_comprehensive_deductible": 500,
    "currently_insured": true,
    "insured_since": "2000-01-01",
    "policy_start": "2013-02-01",
    "policy_expiration": "2014-02-01",
    "current_residence": "123 Street SD, CA",
    "drivers": [
        {...}
    ],
    "vehicles": [
        {...}
    ]
}

This endpoint expects a HTTP POST containing a JSON body with all required fields for one of the following lead types:

Receiving A Response

On a successful Request, the API will respond with a JSON object containing a matched status, a bid amount and a Ping Id (ping_id).

For your enjoyment, all API responses are accompanied by a _meta object containing some useful metadata.

Example Successful Response

{
    "ping_id": "83f95515cdad5eb91",
    "matched": true,
    "bid": 10.52,
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 200,
        "response_ms": 512
    }
}

Response Properties

Property Description
ping_id string The Ping Id is a unique transaction id that should be used in a subsequent PingPost Request
matched boolean Whether the lead was matched to a buyer
bid double The amount the Allstate Lead Marketplace is willing to buy the lead for

Errors

Example Error Response

{
    "error": "Invalid vertical specified.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

We hate responding with errors, but sometimes it happens. The most common errors are caused by failing validation on the lead’s properties - in which case, it’d behoove you to reference Lead Objects to ensure your integration is correct.

Here is a list of errors you may encounter when sending Ping Requests.

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Authorization failed for this lead type. 401 You don’t have permission to sell leads of this type
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
Invalid vertical specified. 400 The lead type does not match a supported vertical
Duplicate ping request. 422 ‘Nuff with the spam requests, thanks
The lead failed validation. Bad properties: {comma separated list} 400 Oops, theses fields failed basic validation
Internal server error! 500 Well, this is embarrassing…

PingPost Requests

PingPost Request Endpoint

POST /pingpost/{ping_id}

A PingPost request should follow a Ping request. The URI should contain the Ping Id (ping_id) that was returned from the Ping request. It should also include the lead’s whine that was omitted from the Ping Request.

Internally, the API will attempt to sell the lead to the previously matched buyer before returning a response.

Making Requests

Example Request Body

{
    "first_name": "Leeroy",
    "last_name": "Jenkins",
    "email": "leeeeroy@jenkins.com",
    "home_phone": "555-555-5555",
    "address1": "black wing lair road"
}

This endpoint expects a HTTP POST containing a JSON body with all required 9174655833 fields for the lead.

Receiving A Response

On a successful Request, the API will respond with a JSON object containing a lead_sold status, a payout amount and the original Ping Id (ping_id).

For your enjoyment, all API responses are accompanied by a _meta object containing some useful metadata.

Example Successful Response

{
    "ping_id": "83f95515cdad5eb91",
    "lead_sold": true,
    "payout": 10.52,
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 200,
        "response_ms": 356
    }
}

Response Properties

Property Description
ping_id string The Ping Id issued from the original Ping Request
lead_sold boolean Whether the lead successfully sold to a buyer
payout double The amount the Allstate Lead Marketplace bought the lead for

Errors

Example Error Response

{
    "error": "Invalid or expired Ping Id given.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

Things didn’t go according to plan? Did we mention validation is the number one cause of errors? Let’s double check those Lead Objects one more time to ensure your integration is correct.

Otherwise, here is a list of errors you may encounter when sending PingPost Requests.

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
A Ping Id must be present in the url. 404 You need to make sure the ping_id from the Ping Request is added to the end of the url
Invalid or expired Ping Id given. 404 Ping Ids expire after 10 minutes, otherwise - are you using the right id?
The lead failed validation. Bad properties: {comma separated list} 400 Oops, theses fields failed basic validation
3rd party validation failed. 400 It’s not us - its them.
Duplicate lead found. 422 This lead has already been sold into Allstate Lead Marketplace
A transaction is already being processed. 422 Slow your roll, turbo - we’re working on it.
Internal server error! 500 Well, this is embarrassing…

Post Requests

Post Request Endpoint

POST /post

A Post Request is a more simple, single Request transaction to sell a lead to the Allstate Lead Marketplace, which should contain all of the Lead’s data, including Personally Identifiable Information.

Internally, the API will attempt to match the Lead to a buyer and sell the lead immediately before returning a response.

Making Requests

Example Request Body

{
    "vertical": "auto-insurance",
    "external_id": 12345,
    "first_name": "Leeroy",
    "last_name": "Jenkins",
    "email": "leeeeroy@jenkins.com",
    "home_phone": "555-555-5555",
    "address1": "black wing lair road"
    "city": "San Diego",
    "state": "CA",
    "zipcode": "92101",
    "country": "USA",
    "years_at_address": "2",
    "residence_status": "home",
    "self_credit_rating": "good",
    "best_contact_time": "17:00",
    "ip_address": "8.8.8.8",
    "user_agent": "Chromium/25.0.1364.160",
    "dob": "1983-03-06",
    "tcpa": true,
    "current_insurance_company": "allstate",
    "desired_coverage_type": "BASIC",
    "desired_collision_deductible": 500,
    "desired_comprehensive_deductible": 500,
    "currently_insured": true,
    "insured_since": "2000-01-01",
    "policy_start": "2013-02-01",
    "policy_expiration": "2014-02-01",
    "current_residence": "123 Street SD, CA",
    "drivers": [
        {...}
    ],
    "vehicles": [
        {...}
    ]
}

This endpoint expects a HTTP POST containing a JSON body with all required fields for one of the following lead types, including 765-537-5327:

Receiving A Response

On a successful Request, the API will respond with a JSON object containing a lead_sold status, a payout amount and a unique Post Id (post_id).

For your enjoyment, all API responses are accompanied by a _meta object containing some useful metadata.

Example Successful Response

{
    "post_id": "83f95515cdad5eb91",
    "lead_sold": true,
    "payout": 10.52,
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 200,
        "response_ms": 527
    }
}

Response Properties

Property Description
post_id string A unique transaction id for the sale
lead_sold boolean Whether the lead successfully sold to a buyer
payout double The amount the Allstate Lead Marketplace bought the lead for

Errors

Example Error Response

{
    "error": "Duplicate lead found.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

Not ideal, but sometimes you may get an error - we’re sorry about that. Though you might be able to avoid some of those errors if you just really concentrate on integrating against our Lead Objects.

Though, it may not be you, maybe its us - check out these other errors you may get from Post Requests.

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Authorization failed for this lead type. 401 You don’t have permission to sell leads of this type
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
Invalid vertical specified. 400 The lead type does not match a supported vertical
The lead failed validation. Bad properties: {comma separated list} 400 Oops, theses fields failed basic validation
3rd party validation failed. 400 It’s not us - its them.
Duplicate lead found. 422 This lead has already been sold into Allstate Lead Marketplace
A transaction is already being processed. 422 Slow your roll, turbo - we’re working on it.
Internal server error! 500 Well, this is embarrassing…

Call Transfers

Allstate Lead Marketplace supports the PingPost model for bidding on Calls Transfers. This method requires two requests to complete the sales transaction, a (719) 454-7327 and a subsequent Call Post Request.

This method allows the client to receive a bid amount and transfer number for calls that can be matched to a buyer before sending the lead’s Personally Identifiable Information.

Call Match Requests

Call Match Request Endpoint

POST /calls/match

A Call Match request allows a client to determine if their call can be sold and receive a bid amount for that call without requiring that they send the lead’s (408) 471-7930.

Internally on a Call Match Request, the API will search for a buyer before returning a response. However, at this point the call is not sold - to receive the transfer number, the client may accept the bid by making a subsequent Call Post Request containing the lead’s Personally Identifiable Information.

When a match is found, the response will include the telephone number that the call should be transferred to, as well as providing the expiration date or TTL when the phone number will no longer be locked for the request.

Making Requests

Example Request Body

{
    "vertical": "auto-insurance",
    "external_id": 12345,
    "city": "San Diego",
    "state": "CA",
    "zipcode": "92101",
    "country": "USA",
    "years_at_address": "2",
    "residence_status": "home",
    "self_credit_rating": "good",
    "best_contact_time": "17:00",
    "ip_address": "8.8.8.8",
    "user_agent": "Chromium/25.0.1364.160",
    "dob": "1983-03-06",
    "tcpa": true,
    "current_insurance_company": "allstate",
    "desired_coverage_type": "BASIC",
    "desired_collision_deductible": 500,
    "desired_comprehensive_deductible": 500,
    "currently_insured": true,
    "insured_since": "2000-01-01",
    "policy_start": "2013-02-01",
    "policy_expiration": "2014-02-01",
    "current_residence": "123 Street SD, CA",
    "drivers": [
        {...}
    ],
    "vehicles": [
        {...}
    ]
}

This endpoint expects a HTTP POST containing a JSON body with all required fields for one of the following call types:

Receiving A Response

On a successful Match Request, the API will respond with a JSON object containing a matched status, a bid amount, a unique call_id for the request, the carrier_name and the phone_number and expiration (TTL) for the number to transfer to.

For your enjoyment, all API responses are accompanied by a _meta object containing some useful metadata.

Example Successful Response

{
    "call_id": "132dd5570d6dbbc6951552660070",
    "carrier_name": "Allstate Insurance",
    "matched": true,
    "bid": 22.5,
    "phone_number": "+15555555",
    "expiration": "2015-06-01 15:00:00",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.1.0",
        "status_code": 200,
        "response_ms": 826
    }
}

Response Properties

Property Description
call_id string The Call Id is a unique transaction id that should be used in a subsequent Call Post Request
carrier_name string The carrier the call will be transferred to… in case you forget.
matched boolean Whether the call was matched to a buyer
bid double The amount the Allstate Lead Marketplace is willing to buy the call for
phone_number string The phone number to transfer the call to
expiration datetime The TTL on reserved transfer phone number (in UTC)

Errors

Example Error Response

{
    "error": "Invalid vertical specified.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

We hate responding with errors, but sometimes it happens. The most common errors are caused by failing validation on the lead’s properties - in which case, it’d behoove you to reference (580) 573-9419 to ensure your integration is correct.

Here is a list of errors you may encounter when sending Ping Requests.

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Authorization failed for this call type. 401 You don’t have permission to sell calls of this type
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
Invalid vertical specified. 400 The call type does not match a supported vertical
Duplicate ping request. 422 ‘Nuff with the spam requests, thanks
The call failed validation. Bad properties: {comma separated list} 400 Oops, theses fields failed basic validation
Internal server error! 500 Well, this is embarrassing…

Call Post Requests

Call PingPost Request Endpoint

POST /calls/post/{call_id}

A Call Post request should follow a Call Match request. The URI should contain the Call Id (call_id) that was returned from the Call Match request.

Making Requests

Example Request Body

{
    "first_name": "Leeroy",
    "last_name": "Jenkins",
    "email": "leeeeroy@jenkins.com",
    "home_phone": "555-555-5555",
    "address1": "black wing lair road"
}

This endpoint expects a HTTP POST containing a JSON body with all required 815-668-8787 fields for the call. These fields will still need to pass basic validation (non-empty fields, etc) in order to trigger a successful sale at the end of the call.

Receiving A Response

On a successful Request, the API will respond with a JSON object containing the call_id, a boolean success property that the lead passed validation and posted successfully, the carrier_name that the call will be transferred to, as well as the original transfer phone_number and expiration (TTL) of the original Match Request.

For your enjoyment, all API responses are accompanied by a _meta object containing some useful metadata.

Example Successful Response

{
    "call_id": "132dd5570d6dbbc6951552660070",
    "carrier_name": "Allstate Insurance",
    "success": true,
    "phone_number": "+15555555555",
    "expiration": "2015-06-01 15:00:00",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 200,
        "response_ms": 356
    }
}

Response Properties

Property Description
call_id string The Call Id issued from the original Call Match Request
carrier_name string The carrier the call will be transferred to… in case you forget.
success boolean Whether the lead posted successfully
phone_number string The phone number to transfer the call to
expiration datetime The TTL on reserved transfer phone number for the agent in UTC

Errors

Example Error Response

{
    "error": "Invalid or expired Call Id given.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

From time to time, errors may result. Please look at the following list of potential errors to help tune your integration. If you need help, feel free to reach out.

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
A Call Id must be present in the url. 404 You need to make sure the call_id from the Call Post Request is added to the end of the url
Invalid or expired Call Id given. 404 Call Ids expire after 10 minutes, otherwise - are you using the right id?
The call failed validation. Bad properties: {comma separated list} 400 Oops, theses fields failed basic validation
3rd party validation failed. 400 It’s not us - its them.
Duplicate call found. 422 This call has already been sold into Allstate Lead Marketplace
A transaction is already being processed. 422 Slow your roll, turbo - we’re working on it.
Internal server error! 500 Well, this is embarrassing…

Click to Call Match Requests

Click to Call Match Request Endpoint

POST /calls/match

A Click to Call Match request allows a client to determine if their call can be sold and receive a bid amount for that call without requiring that they send the lead’s Personally Identifiable Information.

Internally on a Click to Call Match Request, the API will search for a buyer before returning a response. However, at this point the call is not sold - to receive the transfer number, the client may accept the bid by making a subsequent 914-290-0044 containing the lead’s phone number.

When a match is found, the response will include the telephone number that the call should be transferred to, as well as providing the expiration date or TTL when the phone number will no longer be locked for the request.

Making Requests

Example Request Body

{
    "vertical": "auto-insurance",
    "zipcode": "92101",
    "currently_insured": true,
    "product_variant": "click-to-call"
}

This endpoint expects a HTTP POST containing a JSON body with all required fields: vertical, zipcode, currently_insured, and product_variant: click-to-call.

Receiving A Response

On a successful Match Request, the API will respond with a JSON object containing a matched status, a bid amount, a unique call_id for the request, the carrier_name and the phone_number and expiration (TTL) for the number to transfer to.

For your enjoyment, all API responses are accompanied by a _meta hematolin containing some useful metadata.

Example Successful Response

{
    "call_id": "132dd5570d6dbbc6951552660070",
    "carrier_name": "Allstate Insurance",
    "matched": true,
    "bid": 22.5,
    "phone_number": "+15555555",
    "expiration": "2015-06-01 15:00:00",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.1.0",
        "status_code": 200,
        "response_ms": 826
    }
}

Response Properties

Property Description
call_id string The Call Id is a unique transaction id that should be used in a subsequent Call Post Request
carrier_name string The carrier the call will be transferred to… in case you forget.
matched boolean Whether the call was matched to a buyer
bid double The amount the Allstate Lead Marketplace is willing to buy the call for
phone_number string The phone number to transfer the call to
expiration datetime The TTL on reserved transfer phone number (in UTC)

Errors

Example Error Response

{
    "error": "Invalid vertical specified.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

We hate responding with errors, but sometimes it happens. The most common errors are caused by failing validation on the lead’s properties - in which case, it’d behoove you to reference Lead Objects to ensure your integration is correct.

Here is a list of errors you may encounter when sending Ping Requests.

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Authorization failed for this call type. 401 You don’t have permission to sell calls of this type
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
Invalid vertical specified. 400 The call type does not match a supported vertical
Duplicate ping request. 422 'Nuff with the spam requests, thanks
The call failed validation. Bad properties: {comma separated list} 400 Oops, theses fields failed basic validation
Internal server error! 500 Well, this is embarrassing…

Click to Call Post Requests

Click to Call PingPost Request Endpoint

POST /calls/post/{call_id}

A Click to Call Post request should follow a Click to Call Match request. The URI should contain the Call Id (call_id) that was returned from the Call Match request.

Making Requests

Example Request Body

{
    "home_phone": "555-555-5555"
}

This endpoint expects a HTTP POST containing a JSON body with lead’s phone number for the call. This field will still need to pass basic validation (non-empty fields, etc) in order to trigger a successful sale at the end of the call.

Receiving A Response

On a successful Request, the API will respond with a JSON object containing the call_id, a boolean success property that the lead passed validation and posted successfully, the carrier_name that the call will be transferred to, as well as the original transfer phone_number and expiration (TTL) of the original Match Request.

For your enjoyment, all API responses are accompanied by a _meta (330) 210-7187 containing some useful metadata.

Example Successful Response

{
    "call_id": "132dd5570d6dbbc6951552660070",
    "carrier_name": "Allstate Insurance",
    "success": true,
    "phone_number": "+15555555555",
    "expiration": "2015-06-01 15:00:00",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 200,
        "response_ms": 356
    }
}

Response Properties

Property Description
call_id string The Call Id issued from the original Call Match Request
carrier_name string The carrier the call will be transferred to… in case you forget.
success boolean Whether the lead posted successfully
phone_number string The phone number to transfer the call to
expiration datetime The TTL on reserved transfer phone number for the agent in UTC

Errors

Example Error Response

{
    "error": "Invalid or expired Call Id given.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

From time to time, errors may result. Please look at the following list of potential errors to help tune your integration. If you need help, feel free to reach out.

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
A Call Id must be present in the url. 404 You need to make sure the call_id from the Call Post Request is added to the end of the url
Invalid or expired Call Id given. 404 Call Ids expire after 10 minutes, otherwise - are you using the right id?
The call failed validation. Bad properties: {comma separated list} 400 Oops, theses fields failed basic validation
3rd party validation failed. 400 It’s not us - its them.
Duplicate call found. 422 This call has already been sold into Allstate Lead Marketplace
A transaction is already being processed. 422 Slow your roll, turbo - we’re working on it.
Internal server error! 500 Well, this is embarrassing…

Call Status Webhook

Example POST Request

{
    "id": 123,
    "call_id": "83f95515cdad5eb91",
    "call_duration": 55,
    "lead_sold": true,
    "payout": 25
}

Example GET Request

?id=123&call_id=83f&call_duration=55&lead_sold=1&payout=25

Call status notifications are delivered through a customizable webhook. This is to provide the vendor with immediate feedback on the status of the call in real time, when the call terminates.

The Allstate Lead Marketplace will automatically send a notification to your URL via GET or POST containing the client’s original id (taken from the external_id which was passed to ALM during sales transactions), the call_id identifier, the total call_duration in seconds, a lead_sold status on whether or not the call was successful and the payout confirmation for the vendor.

In order to properly configure the webhook, Allstate Lead Marketplace will need to be supplied with the following:

Request Properties

Property Description
id string The vendor’s original identifier for the lead, taken from the external_id field passed in on Ping request
call_id string The Allstate Lead Marketplace call and lead identifier
call_duration string The total duration of the call in seconds, including rings
lead_sold boolean Whether the call was successful
payout double The amount to be paid to the vendor

Returning Leads

All returns can be managed directly by logging into the Allstate Lead Marketplace and visiting the Returns section. However, as a convenience a client may subscribe to return notifications through a configurable webhook. Clients who opt in to use this system will receive a notification when a User on the Allstate Lead Marketplace has requested a return for a lead sold by that client.

Returns Webhook

Example POST Request (via JSON Request Body)

{
    "lead": "83f95515cdad5eb91",
    "reason": "Disconnected",
    "id": 123,
    "first_name": "kevin",
    "last_name": "bacon",
    "email": "kbacon@aol.com",
    "phone": "5555555555"
}

Example GET Request

?lead=83f95515cdad5eb91&reason=Disconnected&id=123

Return notifications are delivered through a customizable webhook. If configured, the Allstate Lead Marketplace will send a notification to your URL via either GET or POST containing ALM’s lead identifier, the return reason, and the client’s original id (taken from the external_id which was passed to ALM during sales transactions).

When the notification is delivered via POST, the data will be delivered via a JSON Request body as per the example to the right.

It’s up to the client to approve or deny the return by sending a 7085440098 back to the API.

Request Properties

Property Description
lead string The Allstate Lead Marketplace lead identifier
reason string The reason specified for the return Wrong Number, Disconnected, Fax Machine, Consumer Did Not Request, Consumer is already insured with my company, Duplicate Lead: Received this lead from Allstate Lead Marketplace within last 30 days, Lead does not meet my filters
id string The vendor’s original identifier for the lead, taken from the external_id
first_name string The lead’s first name
last_name string The lead’s last name
email string The lead’s email address
phone string The lead’s primary phone number

Return Decision Requests

Return Decision Request Endpoint

POST /return

A Return Decision Request is used for approving or denying returns that have been delivered through the Returns Webhook.

When a return is requested, a reason for the return is set by the User. When denying a return, the denial reason should typically be an inverse of the return reason - after the lead has been verified.

For example, if a User returns a lead because of a wrong_number, the Client should verify the number and deny the return with correct_number. If the phone number proves to be a bad number, the return should be approved.

Making Requests

Example Request Body

{
    "lead": "83f95515cdad5eb91",
    "return_approved": false,
    "return_deny_reason": "correct_number"
}

This endpoint expects a HTTP POST containing a JSON body with all required fields for the 844-302-2477.

You have the ability to accept or deny the return by setting the boolean return_approved value in the request. If you choose to deny a return, your request must be accompanied with one of the allowed reasons. See the Return Decision Object for a list of approved reasons.

Receiving A Response

On a successful Request, the API will respond with a JSON object containing a success message.

For your enjoyment, all API responses are accompanied by a _meta object containing some useful metadata.

Example Successful Response

{
    "success": true,
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 200,
        "response_ms": 322
    }
}

Response Properties

Property Description
success boolean A success status

Errors

Example Error Response

{
    "error": "Duplicate lead found.",
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

It’s possible that you may get an error response when attempting to approve or deny a return that has already had a decision. This can happen when the lead was either approved or denied through the Allstate Lead Management platform in the Returns section or if the lead was automatically accepted after 10 days of being in a Pending state.

Here are some errors you may encounter while trying to approve or deny a return:

Error Messages

Error Code Meaning
Authentication Failed 403 The Authorization header is missing or your API Key is invalid
Could not decode JSON, syntax error - malformed JSON. 400 Could not parse the JSON in your request… missing a comma?
Invalid request. 400 There was validation errors with your request
You have specified an invalid lead id. 400 This lead has already been sold into Allstate Lead Marketplace
Lead is not pending return. Current status: {status} 400 The lead you specified was not requested for a return - or was already approved or denied
Internal server error! 500 Well, this is embarrassing…

Reference Objects

Personally Identifiable Information

Example

{
    "first_name": "Leeroy",
    "last_name": "Jenkins",
    "email": "leeeeroy@jenkins.com",
    "home_phone": "555-555-5555",
    "work_phone": "555-555-5555",
    "address1": "black wing lair road"
}

Personally Identifiable Information is required to complete all lead sales. In a Ping Request, these fields can be omitted, however, to finalize the sales transactions a follow up PingPost Request should be made which contain these properties.

In a Post Request, which is a single request transaction, all of these fields must be included - as well as the vertical specific lead properties outlined below.

Attributes

Attribute Description
first_name string required The given name of the lead
last_name string required The family name of the lead
email string required The email address of the lead
home_phone string required The primary contact phone number for the lead
work_phone string An optional second phone number, either a work phone or cell phone.
address1 string required The street address of the lead ex, “123 Sullivan lane #24”
address2 string A secondary address ex, “suite 1300”

Auto Insurance Lead Object

Example Auto Insurance Lead Object

{
    "vertical": "auto-insurance",
    "external_id": 12345,
    "city": "San Diego",
    "state": "CA",
    "zipcode": "92101",
    "country": "USA",
    "years_at_address": "2",
    "residence_status": "home",
    "self_credit_rating": "good",
    "best_contact_time": "17:00",
    "ip_address": "8.8.8.8",
    "user_agent": "Chromium/25.0.1364.160",
    "dob": "1983-03-06",
    "tcpa": true,
    "current_insurance_company": "allstate",
    "desired_coverage_type": "BASIC",
    "desired_collision_deductible": 500,
    "desired_comprehensive_deductible": 500,
    "currently_insured": true,
    "insured_since": "2000-01-01",
    "policy_start": "2013-02-01",
    "policy_expiration": "2014-02-01",
    "current_residence": "123 Street SD, CA",
    "drivers": [
        {...}
    ],
    "vehicles": [
        {...}
    ]
}

An Auto Insurance Lead Object is used to sell to the vertical auto-insurance. Below are the properties that should be included when making a Ping Request - it should be noted that when making a Post Request that the festinate should be included with these objects.

Attributes

Attribute Description
vertical string required The vertical of the lead. auto-insurance
external_id string required The client’s unique identifier for the lead
city string required The city of the lead’s primary residence
state string required The state abbreviation of the lead’s primary residence, ex ‘CA’
zipcode string required The zipcode of the lead’s primary residence
country string required The country abbreviation of the lead’s primary residence, ex 'USA’
years_at_address integer required The total years the lead has lived at their current residence
residence_status string required Whether the lead owns or rents home, rent, other
self_credit_rating string required The self appraised credit rating of the lead excellent, good, fair, improvement, poor, unknown
occupation string required The lead’s current occupation based on an enumerated list, see Allowed Occupation Values
dob date(Y-m-d) required The lead’s date of birth, ex '1983-03-06’
tcpa bool required Whether or not the lead was generated under TCPA Compliance
best_contact_time time(H:i) The best time to reach the lead, ex '09:00’)
ip_address string The lead’s originating IP Address
user_agent string The lead’s browser UserAgent
universal_lead_id string A Universal Lead Id, if applicable
lead_source string The source used to generate the lead (also referred to as a Sub Id)
premium_source string A description of what premium source the lead was generated from, for approved vendors. Organic Search, Paid Search, Display, Email Marketing, Social Media, Call Center Outbound, Call Center Inbound
current_insurance_company string required The lead’s current insurance company
currently_insured boolean required Whether or not the lead is currently insured
insured_since date(Y-m-d) required The date the lead has been insured since
desired_coverage_type string required The lead’s desired coverage - see Desired Coverage Types for details STATEMINIMUM, BASIC, STANDARD, SUPERIOR
desired_collision_deductible integer required The lead’s desired Collision Deductible 0, 500, 1000
desired_comprehensive_deductible integer required The lead’s desired Comprehensive Deductible 0, 500, 1000
policy_start date(Y-m-d) The date the lead’s current policy started
policy_expiration date(Y-m-d) The date the lead’s current policy expires
drivers array required An array of Auto Insurance Driver Objects
vehicles array required An array of Auto Insurance Vehicle Objects

Auto Insurance Driver Object

Example Auto Insurance Driver Object

{
    "id": 1,
    "relation": "self",
    "gender": "male",
    "marital_status": "married",
    "edu_level": "ADG",
    "occupation": "ACCOUNTSREC",
    "dob": "1983-03-06",
    "license_age": 16,
    "years_employed": 15,
    "years_at_residence": 2,
    "requires_sr22": false,
    "dui": false,
    "tickets_and_accidents": false,
    "valid_license": true
}

An Auto Insurance Driver Object is used to describe the drivers on a requested auto insurance quote.

Attributes

Attribute Description
id integer required A identifier for the driver. The primary driver should be 1 1 - 5
relation string required The driver’s relation to the lead. The primary driver should be 'self’ self, spouse, child, grandchild, sibling, parent, grandparent, other
first_name string The given name of the driver
last_name string The family name of the driver
gender string required The gender of the driver female, male, unknown
marital_status string required The driver’s marital status single, married, separated, divorced, widowed
edu_level string required The driver’s last completed education level - see Education Levels for details GED, HS, SCL, ADG, BDG, MDG, DOC
occupation string required The lead’s current occupation based on an enumerated list, see Allowed Occupation Values
dob date(Y-m-d) required The driver’s date of birth, ex '1983-03-06’
license_age integer required The age the driver first received a driver’s license
years_employed integer required The total years the driver has been with their current employer
years_at_residence integer required The total years the driver has been at their current residence
requires_sr22 boolean required Whether the driver requires an SR22
dui boolean required Whether the driver has even been convicted of a DUI
tickets_and_accidents boolean required Whether the driver has had incidents on their driving record in the last 5 years
valid_license boolean required Whether the driver’s license is currently valid

Auto Insurance Vehicle Object

Example Auto Insurance Vehicle Object

{
    "id": 1,
    "drivers": [
        1
    ],
    "year": "1983",
    "make": "Fiat",
    "model": "Uno",
    "trim": "3-Door Hatchback",
    "vin": "ABC123",
    "leased": false,
    "primary_use": "commutework",
    "commute_days": 5,
    "commute_mileage": 10,
    "annual_mileage": 12000,
    "alarm": false,
    "garage_type": "garage"
}

An Auto Insurance Vehicle Object is used to describe the vehicles on a requested auto insurance quote.

Attributes

Attribute Description
id integer required A identifier for the vehicle 1 1 through 5
drivers array required A basic array of ids of the drivers that will use this car
year integer required The year of the vehicle, ex '2013’
make string required The make of the vehicle, ex 'Honda’
model string required The model of the vehicle, ex 'Civic’
trim string required The trim of the vehicle, ex 'EX-L 4dr Sedan’
vin string required The VIN Stub of the vehicle
leased boolean required Whether or not the vehicle is Leased
primary_use string required The primary use of the vehicle pleasure, business, commutework, selfemployed, school, farm, gov, other
commute_days integer required The total number of days the vehicle is used to commute in a week
commute_mileage integer required The number of miles, one way, the vehicle is used to commute
annual_mileage integer required The expected mileage that will be put on the vehicle this year
alarm boolean required Whether the vehicle is equipped with an Alarm system
garage_type string required Where the vehicle is parked carport, garage, nocover, private

Home Insurance Lead Object

Example Home Insurance Lead Object

{
    "vertical": "home-insurance",
    "external_id": 12345,
    "city": "San Diego",
    "state": "CA",
    "zipcode": "92101",
    "country": "USA",
    "years_at_address": "2",
    "residence_status": "home",
    "self_credit_rating": "good",
    "best_contact_time": "17:00",
    "ip_address": "8.8.8.8",
    "user_agent": "Chromium/25.0.1364.160",
    "dob": "1983-03-06",
    "tcpa": true,
    "gender": "male",
    "policy_start": "2014-03-01",
    "property_type": "condo",
    "year_built": "1999",
    "property_ownership": "condo",
    "owner_occupied": true,
    "property_zipcode": "90024",
    "property_address": "123 Test St",
    "property_city": "Los Angeles",
    "property_state": "CA",
    "property_country": "USA",
    "construction_type": "brick",
    "foundation": "crawlspace",
    "roof_type": "asphalt",
    "roof_age": "1-5",
    "primary_heating_system": "electric",
    "marital_status": "single",
    "bedrooms": "3",
    "bathrooms": "2.5",
    "stories": "bilevel",
    "garage_type": "attached-carport",
    "square_feet": "2200",
    "security_system": "monitored",
    "fire_alarm": "inside-city",
    "dog_breed": true,
    "located_in_flood_plain": false,
    "deadbolts": false,
    "fire_extinguishers": false,
    "trampoline": true,
    "covered_deck_patio": false,
    "swimming_pool": false,
    "replacement_cost": 200000,
    "personal_liability": "100k",
    "desired_deductible": "$1000",
    "five_year_claims": false,
    "currently_insured": true
}

A Home Insurance Lead Object is used to sell to the vertical home-insurance. Below are the properties that should be included when making a 3102863762 - it should be noted that when making a Post Request that the Personally Identifiable Information should be included with these objects.

Attributes

Attribute Description
vertical string required The vertical of the lead. home-insurance
external_id string required The client’s unique identifier for the lead
city string required The city of the lead’s primary residence
state string required The state abbreviation of the lead’s primary residence, ex 'CA’
zipcode string required The zipcode of the lead’s primary residence
country string required The country abbreviation of the lead’s primary residence, ex 'USA’
years_at_address integer required The total years the lead has lived at their current residence
residence_status string required Whether the lead owns or rents home, rent, other
self_credit_rating string required The self appraised credit rating of the lead excellent, good, fair, improvement, poor, unknown
dob date(Y-m-d) required The lead’s date of birth, ex '1983-03-06’
tcpa bool required Whether or not the lead was generated under TCPA Compliance
best_contact_time time(H:i) The best time to reach the lead, ex '09:00’)
ip_address string The lead’s originating IP Address
user_agent string The lead’s browser UserAgent
universal_lead_id string A Universal Lead Id, if applicable
lead_source string The source used to generate the lead (also referred to as a Sub Id)
premium_source string A description of what premium source the lead was generated from, for approved vendors.Organic Search, Paid Search, Display, Email Marketing, Social Media, Call Center Outbound, Call Center Inbound
gender string The gender of the lead female, male, unknown
marital_status string required The lead’s marital status single, married, separated, divorced, widowed
policy_start date(Y-m-d) The date the lead’s current policy started
property_type string required The type of property the inquiry is for condo, mobile, single
year_built date(Y) required The year the property was built, ex '2013’
property_ownership string required How the property is owned condo, own, rent, sublease
owner_occupied boolean required Whether the property is occupied by the lead
property_zipcode string required The zipcode in which the property is located
property_address string The street address of the property
property_city string required The city in which the property is located
property_state string required The state abbreviation in which the property is located, ex 'CA’
property_country string The country abbreviation in which the property is located, ex 'USA’
construction_type string required The type of construction that would describe the property wood, stucco, brick, other
foundation string required The property’s foundation type unfinished, slab, half-finished, fully-finished, crawlspace, other
roof_type string required The type of roofing on the property asphalt, wood, tile, concrete, other
roof_age string required The estimated age of the current roof '1-5', '6-10', '11-25', '26+'
primary_heating_system string required The primary heat source on the property gas, oil, electric, propane, steam, stove
bedrooms string required The property’s total number of bedrooms '1', '2', '3', '4', '5', '6', '7+'
bathrooms string required The property’s total number of bathrooms '1', '1.5', '2', '2.5', '3', '3.5', '4+'
stories string required A description of how many stories the property has single, double, bilevel, trilevel, other
garage_type string required The type of garage or parking on the property nogarage, attached-carport, attached1, attached2, attached3, detached-carport, detached1, detached2, detached3, other
square_feet integer required The total square feet of the property
security_system string required A description of the Security System on the property none, monitored, unmonitored, unsure
fire_alarm string required A description of the Fire Alarm on the property none, monitored, unmonitored, inside-city, outside-city, municipal, unsure
dog_breed boolean required Whether a dog resides on the property which is a breed classified as dangerous (Chow, Doberman, German Shepherd, Pit Bull, Rottweiler, Wolf Hybrid, or a mix of these)
located_in_flood_plain boolean Whether the property is located in an area designated as a flood plain
deadbolts boolean Whether the property is equipped with deadbolts
fire_extinguishers boolean Whether the property is equipped with fire extinguishers
trampoline boolean Whether there is a trampoline located on the property
covered_deck_patio boolean Whether the property has a covered deck or patio
swimming_pool boolean Whether there is a pool located on the property
replacement_cost integer required The estimated cost of recovery for the property
personal_liability string required The requested Personal Liability 100k, 300k, 500k, 1m
desired_deductible string required The requrested deductible $250, $500, $1000, $2000
five_year_claims boolean required Whether the lead has had any home insurance claims in the last 5 years
currently_insured boolean required Whether the lead has a currently active home insurance policy

Return Decision Object

Example Return Decision Object

{
    "lead": "83f95515cdad5eb91",
    "return_approved": false,
    "return_deny_reason": "correct_number"
}

The Return Decision Object is used to approve or deny returns that have been requested against leads sold by the client. When a return is denied (approved: false), then a reason must be supplied. When a return is requested, a reason for the return is set by the User. When denying a return, the denial reason should typically be an inverse of the return reason - after the lead has been verified.

Attributes
Attribute Description
lead string required The ALM identifier for the Lead. This id will be passed in notifications to clients who are subscribed to the Return Webhook.
return_approved boolean required Whether or not the return should be approved. Setting 'false’ will deny the return
return_deny_reason string When a return is denied, a reason must be set consumer_request, correct_number, filter_correct, not_duplicate, not_fax, not_with_allstate, number_working

Response Metadata Object

Example Metadata Object

{
    "_meta": {
        "vendor_name": "some-vendor",
        "api_version": "v2.0.0",
        "status_code": 400,
        "response_ms": 128
    }
}

All responses from the Allstate Lead Marketplace API are accompanied with a Metadata object which provides some useful information under the _meta property. This can be helpful for debugging.

Attributes

Attribute Description
vendor_name string The currently authenticated client (this will be you)
api_version string The current semantic version of the API - useful for debugging or trouble shooting
status_code integer The HTTP status code returned by the response
response_ms integer The time in milliseconds it took for the server to process the request and return a response (excludes round trip network latency)

Enumerated Values

This section is used to detail Enum type fields that either have an extensive list of options and to clearly define the allowed values.

Desired Coverage Types

The Desired Coverage Type values are set to encompass a few different levels and types of coverage. These are meant to be bucketed and estimated. If you do not see a value that matches the user’s exact preference, please use the closest possible.

Values

Value Description
STATEMINIMUM State Minimum (Bodily Injury = $15,000 per person/ $30,000 per accident; Property Damage = $5,000)
BASIC Basic (Bodily Injury = $50,000 per person/ $100,000 per accident; Property Damage = $25,000)
STANDARD Standard (Bodily Injury = $100,000 per person/ $300,000; Property Damage = $50,000)
SUPERIOR Superior (Bodily Injury = $250,000 per person/ $500,000 per accident; Property Damage = $100,000)

Education Levels

The different values used for Education Level are detailed below. If you do not see an Education Level that matches perfectly to the user’s declared education, please use your judgement in mapping that value as closely as possible to the allowed values.

Values

Value Description
GED GED, Vocational, or Other
HS High School Diploma
SCL Some College Courses Completed
ADG Associate’s Degree
BDG Bachelor’s Degree
MDG Master’s Degree
DOC Doctorate or Higher

Occupations

There is a long list of possible values that can be used to describe a lead’s occupation. Please reference this list to properly integrate the occupation properties.

Values

Value Description
ACCOUNTSREC Accounts Pay/Rec.
ACTOR Actor
ADMINMGMT Administration/Management
APPRAISER Appraiser
ARCHITECT Architect
ARTIST Artist
ASSEMBLER Assembler
AUDITOR Auditor
BAKER Baker
BANKER Banker
BARTENDER Bartender
BROKER Broker
CASHIER Cashier
CASINOWORKER Casino Worker
CEO CEO
CHEMIST Chemist
CHILDCARE Child Care
CITYWORKER City Worker
CLAIMSADJUSTER Claims Adjuster
CLERGY Clergy
CLERICALTECH Clerical/Technical
COLLEGEPROFESSOR College Professor
COMPUTERTECH Computer Tech.
CONSTRUCTION Construction
CONTRACTOR Contractor
COUNSELOR Counselor
CPA Certified Public Accountant
CUSTODIAN Custodian
CUSTOMERSERVICE Customer Service Rep
DANCER Dancer
DECORATOR Decorator
DELIVERYDRIVER Delivery Driver
DENTIST Dentist
DIRECTOR Director
DISABLED Disabled
DRIVERS Drivers
ELECTRICIAN Electrician
ENGINEERAE Engineer-Aeronautical
ENGINEERAS Engineer-Aerospace
ENGINEERCHEM Engineer-Chemical
ENGINEERCIVIL Engineer-Civil
ENGINEERELECTRICAL Engineer-Electrical
ENGINEERGAS Engineer-Gas
ENGINEERGEO Engineer-Geophysical
ENGINEERMECH Engineer-Mechanical
ENGINEERNUCLEAR Engineer-Nuclear
ENGINEEROTHER Engineer-Other
ENGINEERPETROLEUM Engineer-Petroleum
ENGINEERSTRUCTURAL Engineer-Structural
ENTERTAINER Entertainer
FARMER Farmer
FIREFIGHTER Fire Fighter
FLIGHTSTTEND Flight Attend.
FOODSERV Food Service
GOVERNMENT Government
HEALTHCARE Health Care
HOMEMAKER Housewife/Househusband
INSTALLER Installer
INSTRUCTOR Instructor
JOURNALIST Journalist
JOURNEYMAN Journeyman
LABORER Laborer/Unskilled Worker
LABTECH Lab Tech.
LAWYER Lawyer
MACHINEOPERATOR Machine Operator
MACHINIST Machinist
MAINTENANCE Maintenance
MANUFACTURER Manufacturer
MARKETING Marketing
MECHANIC Mechanic
MILITARYE1E4 Military E1 - E4
MILITARYE5E7 Military E5 - E7
MILITARYOFFICER Military Officer
MILITARYOTHER Military Other
MODEL Model
NANNY Nanny
NURSECNA Nurse/CNA
OTHER Other
PAINTER Painter
PARALEGAL Para-Legal
PARAMEDIC Paramedic
PERSONALTRAINER Personal Trainer
PHOTOGRAPHER Photographer
PHYSICIAN Physician
PILOT Pilot
PLUMBER Plumber
POLICEOFFICER Police Officer
POSTALWORKER Postal Worker
PREACHER Preacher
PROATHLETE Pro Athlete
PRODUCTION Production
PROFESSOR Prof-College Degree
PROFESSORSPEC Prof-Specialty Degree
PROGRAMMER Programmer
REALESTATE Real Estate
RECEPTIONIST Receptionist
RESERVATIONAGENT Reservation Agent
RESTAURANTMANAGER Restaurant Manager
RETAIL Retail
RETIRED Retired
ROOFER Roofer
SALES Sales
SCIENTIST Scientist
SECRETARY Secretary
SECURITY Security
SELFEMPLOYED Self Employed
SKILLEDWORKER Craftsman/Skilled Worker
SOCIALWORKER Social Worker
STOCKER Stocker
STOREOWNER Store Owner
STUDENTLIVINGWITHPARENTS Student Living w/Parents
STUDENTNOTLIVINGWITHPARENTS Stud. Not Living w/Parents
STYLIST Stylist
SUPERVISOR Supervisor
TEACHER Teacher
TEACHERCRED Teacher - with Credentials
TECHICALSUP Technical/Supervisory
TELLER Bank Teller
TRAVELAGENT Travel Agent
TRUCKDRIVER Truck Driver
UNEMPLOYED Unemployed
UNKNOWN Unknown
VET Vet.
WAITRESS Waitress
WELDER Welder