PingPost REST API v1.0

  1. Introduction
  2. Technical Details
    1. Security
      1. Transport Layer
      2. Authentication
    2. Lead exchange format
    3. API limits
    4. Quality of Service (QoS)
      1. Availability of API
      2. Duplicate Detection
      3. Response Times
  3. Supported Features
    1. Lead types
    2. Exclusive and shared leads
    3. Distribution Directives
    4. Lead source tracking
  4. XML Schema Files
  5. API Details
    1. Direct Lead Post API
      1. API Request
      2. API Response
    2. Data Post API
      1. API Request
      2. API Response
    3. Ping Lead API
      1. API Request
      2. API Response
    4. Post Lead API
      1. API Request
      2. API Response
    5. Legs Ping Lead API
      1. API Request
      2. API Response
    6. Legs Post Lead API
      1. API Request
      2. API Response
    7. Calls API
      1. API Request
      2. API Response
    8. Clicks API
      1. API Request
      2. API Response
  6. API endpoints
  7. Sample XMLs
  1. Introduction
    Back to Contents

    This document details API that Contactability provides to its affiliates to sell leads to Contactability via version 1.0 PingPost REST API.

    This API is secure and protected by user credentials. To access this API, user must have a valid token. Without these credentials (or using wrong credentials), you will get 401 unauthorized error.

    Approved partners can use this API to ping Contactability with the lead that they want to sell us. Contactability will respond with the bid that it is willing to pay for that lead. If accepted, partner can post the full lead to Contactability for the predetermined price.

    Contactability also supports Leg based pingpost functionality. In leg based integration, Contactability will respond with the legs and payouts for individual legs. Partner can approve individual (or all) legs and post lead to us to be sold only to those approved legs.

    To get started, please contact us at - support@contactability.com.

  2. Technical Details
    Back to Contents

    This API is a simple REST API. For both Ping and Post, lead data is accepted in XML format (HTTP POST) and must confirm to schema file.

    1. Security:
      Back to Contents
      1. Transport layer:

        Contactability uses HTTPS (HTTP over SSL) which ensures privacy and integrity of the exchanged data.

      2. Authentication:

        All data partners will be assigned a unique token at the time of sign up. Partners are required to send this token in the XML along with the other data. You will get "401 Forbidden" response in case of token mismatch or absence of token value.

    2. Lead exchange format:
      Back to Contents

      XML. All the lead data must be HTTP POSTed to us in valid XML format confirming to our XML schema.

    3. API Limits:
      Back to Contents

      5/sec. 300/min/ 10000/hour.

    4. Quality of Service (QoS):
      Back to Contents
      1. Availability of API:

        Contactability will make every effort to ensure the API availability 24x7. However during routine maintenance the API may not be available. We will make every effort to keep the disruption to minimal and to communicate to our best ability to the appropriate parties.

        Contactability will return 5XX HTTP response code when the API is not available.

        Please contact our development team at support@contactability.com in case of any concerns or questions regarding the API outage.

      2. Duplicate Detection:

        Contactability will return error code of "Duplicate" in case of duplicate detection on both ping and post.

      3. Response Times:

        Contactability will make every effort to keep the response time on every request to minimal. Currently the average response time is 5 secs. However there are times when the response time is around 10 secs.

        If you are experiencing longer response times, please reach out to us at support@contactability.com

  3. Supported Features
    Back to Contents
    1. Lead Types:

      Contactability supports the following lead types.

      • Auto: LeadTypeID = 1
        • Premium Auto
          • At least 1 driver with age 22 and over
          • All drivers currently insured
          • All drivers with valid licenses
          • No SR22
          • No DUI
          • No Major violations
          • No at fault accidents
          • 1 or less tickets
        • Standard Auto
          • At least 1 driver with age 18 and over
          • All drivers currently insured
          • All drivers with valid licenses
          • No SR22
          • No DUI
          • 1 or less at fault accidents
          • 3 or less tickets
        • Substandard Auto
          • At least 1 driver with age 18 and over
        • Juvenile Auto
          • All drivers under age 18
      • Home: LeadTypeID = 2
      • Renters: LeadTypeID = 3
      • Health: LeadTypeID = 4
      • Life: LeadTypeID = 5
      • Commercial: LeadTypeID = 6
      • Medicare: LeadTypeID = 10
    2. Exclusive and Shared leads:
      Back to Contents

      Contactability allows affiliates to sell both the exclusive and shared leads via this API. If its an exclusive lead, DistributionCount XML parameter should be 0. In case of Shared leads, DistributionCount should be present and must be equal to the number of times the lead is already sold along with DistributionDirectives.

    3. Distribution Directives:
      Back to Contents

      DistributionDirectives must be present if the lead being sold is shared lead. DistributionCount should be present and must be equal to the number of times the lead is already sold. You should also list all the carriers the lead is already sold to inside the Excludes XML element.

      If the lead is sold to an Independent agent, license number should be sent along. You will get 4xx Bad Request error in case of Invalid Distribution Directives.

    4. Lead Source Tracking:
      Back to Contents

      Contactability allows affiliates to send optional lead source inside the XML element LeadSourceID. This allows better reporting and allows to scale up and scale down particular lead source.

  4. XML Schema Files
    Back to Contents
  5. API Details
    Back to Contents
    1. Direct Lead Post API
      1. Direct Lead Post API request
        Back to Contents

        This API endpoint is used to send leads to Contactability for purchase. Lead must be HTTP POSTed to the endpoint and must adhere to the Contactability Post XML schema. Failure to do so will result in 4xx "Bad Request" error.

        This API supports posting both exclusive and shared leads. Leads posted without Distribution directives are considered exclusive leads whereas leads with one or more distribution directives are considered shared leads.

        Lead must be posted with full data along with contact information.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/direct_post

        HTTP POST parameter:

        • xml (string)
          • UTF-8 encoded XML string. Must be in accordance with the Contactability Ping XML schema. Failure to do so will result in 4xx "Bad Request" error.

        Example Direct Post XML - http://dev.contactability.com/ping_post/v1/docs/sample_auto_post.xml

      2. Direct Lead Post API response
        Back to Contents

        Direct Lead Post API will return HTTP response code 200 for all successful post requests. In case of data errors 4xx response code is returned. In case of service outage or any other server errors on Contactability side, a 5xx HTTP response code is returned.

        In case of data validation errors (4xx), more detailed information about the error will be returned under "ErrorType" and "ErrorDescription" XML elements.

        API response XML elements:

        • Result
          It will be either "OK" or "ERROR".
        • ErrorType
          Only present if the Result is "ERROR". Values -
          • Auth Failure - Indicating partner specific info is missing or wrong.
          • Bad Request - Data validation errors.
          • Duplicate - For both duplicate ping and post.
          • Timeout - When attempting to post the lead 5 mins after generating PingID.
          • Server Error - Some error occurred on Contactability side. Please reach out to us at support@contactability if the problem persists.
        • ErrorDescription
          Only present if the Result is "ERROR". Detailed description for "ErrorType".
        • LeadID
          Lead ID under Contactability system.

        Example Direct Lead Post Response XML - http://dev.contactability.com/ping_post/v1/docs/direct_post_response.xml

    2. Data Post API
      1. Data Post API request
        Back to Contents

        This API endpoint is used to send leads to Contactability as an add on service. Lead must be HTTP POSTed to the endpoint and must adhere to the Contactability Post XML schema. Failure to do so will result in 4xx "Bad Request" error.

        Lead must be posted with full data along with contact information.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/data_post

        HTTP POST parameter:

        • xml (string)
          • UTF-8 encoded XML string. Must be in accordance with the Contactability Ping XML schema. Failure to do so will result in 4xx "Bad Request" error.

        Example Data Post XML - http://dev.contactability.com/ping_post/v1/docs/sample_auto_post.xml

      2. Data Post API response
        Back to Contents

        Direct Lead Post API will return HTTP response code 200 for all successful post requests. In case of data errors 4xx response code is returned. In case of service outage or any other server errors on Contactability side, a 5xx HTTP response code is returned.

        In case of data validation errors (4xx), more detailed information about the error will be returned under "ErrorType" and "ErrorDescription" XML elements.

        API response XML elements:

        • Result
          It will be either "OK" or "ERROR".
        • ErrorType
          Only present if the Result is "ERROR". Values -
          • Auth Failure - Indicating partner specific info is missing or wrong.
          • Bad Request - Data validation errors.
          • Duplicate - For both duplicate ping and post.
          • Timeout - When attempting to post the lead 5 mins after generating PingID.
          • Server Error - Some error occurred on Contactability side. Please reach out to us at support@contactability if the problem persists.
        • ErrorDescription
          Only present if the Result is "ERROR". Detailed description for "ErrorType".
        • LeadID
          Lead ID under Contactability system.

        Example Data Post Response XML - http://dev.contactability.com/ping_post/v1/docs/direct_post_response.xml

    3. Ping Lead API
      1. Ping API request
        Back to Contents

        This API endpoint is used to send leads to Contactability to receive our bid on the lead. Lead must be HTTP POSTed to the endpoint and must adhere to the Contactability Ping XML schema. Failure to do so will result in 4xx "Bad Request" error.

        This API supports posting both exclusive and shared leads. Leads posted without Distribution directives are considered exclusive leads whereas leads with one or more distribution directives are considered shared leads.

        Lead must be posted with full data. Contact information on the lead is optional. Contactability will respond to its best bid for this lead on the response.

        When non-zero bid is returned, the response also includes the "PingID" for Contactability system. If bid is accepted, full lead data (along with Contact information) must be posted along with "PingID". Please note the "PingID" is valid for 5 minutes from the time it is assigned. Otherwise 4xx "Timeout" error is returned.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/ping

        HTTP POST parameter:

        • xml (string)
          • UTF-8 encoded XML string. Must be in accordance with the Contactability Ping XML schema. Failure to do so will result in 4xx "Bad Request" error.

        Example Ping XML - http://dev.contactability.com/ping_post/v1/docs/sample_auto.xml

      2. Ping API response
        Back to Contents

        Ping API will return HTTP response code 200 for all successful ping requests. In case of data errors 4xx response code is returned. In case of service outage or any other server errors on Contactability side, a 5xx HTTP response code is returned.

        In case of data validation errors (4xx), more detailed information about the error will be returned under "ErrorType" and "ErrorDescription" XML elements.

        It is possible that Contactability will return payout of zero even for the successful ping (200 response code).

        API response XML elements:

        • Result
          It will be either "OK" or "ERROR".
        • ErrorType
          Only present if the Result is "ERROR". Values -
          • Auth Failure - Indicating partner specific info is missing or wrong.
          • Bad Request - Data validation errors.
          • Duplicate - For both duplicate ping and post.
          • Timeout - When attempting to post the lead 5 mins after generating PingID.
          • Server Error - Some error occurred on Contactability side. Please reach out to us at support@contactability if the problem persists.
        • ErrorDescription
          Only present if the Result is "ERROR". Detailed description for "ErrorType".
        • Payout
          Contactability's bid.
        • PingID
          Only present if the Result is "OK". To be used when posting lead to Post lead API.

        Example Ping Response XML - http://dev.contactability.com/ping_post/v1/docs/ping_response.xml

    4. Post Lead API
      1. Post API request
        Back to Contents

        This API endpoint is used to post leads to Contactability after our bid has been accepted by the affiliate.

        Lead must be posted in accordance with the schema and in its entirety including all Contact information.

        This API calls also includes another HTTP parameter called "ping_id". This PingID must match the identifier previously returned by Ping Lead API. This PingID is valid only for 5 minutes from the time it is generated. Failure to do so will result in 4xx "Timeout" error.

        With the exception of the ping-time optional personally identifying information, the Lead XML provided in this post API must be identical to the XML presented earlier in the associated ping API. If the XML differs, the post will be rejected.

        Prior to accepting the lead, Contactability will check for personal identifying information. If it is not valid then the lead will be rejected. Contactability also performs duplicate check on posts. If the lead is already within the Contactability system it will be rejected with 4xx "Duplicate" error.

        If lead is accepted, Contactability will return "LeadID" and payout. Affiliates are encouraged to store this LeadID for future reference. Payout should match the one returned during corresponding ping API call.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/post

        HTTP POST parameters:

        • ping_id (string)
          A string for the PingID returned by previous successful call to Ping lead API.
        • xml (string)
          UTF-8 encoded XML string. Must be in accordance with the Contactability Ping XML schema. Failure to do so will result in 4xx "Bad Request" error.

        Example Post XML - http://dev.contactability.com/ping_post/v1/docs/sample_auto_post.xml

      2. Post API response
        Back to Contents

        Post API will return HTTP response code 200 for all successful ping requests. In case of data errors 4xx response code is returned. In case of service outage or any other server errors on Contactability side, a 5xx HTTP response code is returned.

        In case of data validation errors (4xx), more detailed information about the error will be returned under "ErrorType" and "ErrorDescription" XML elements.

        API response XML elements:

        • Result
          It will be either "OK" or "ERROR".
        • ErrorType
          Only present if the Result is "ERROR". Values -
          • Auth Failure - Indicating partner specific info is missing or wrong.
          • Bad Request - Data validation errors.
          • Duplicate - For both duplicate ping and post.
          • Timeout - When attempting to post the lead 5 mins after generating PingID.
          • Server Error - Some error occurred on Contactability side. Please reach out to us at support@contactability if the problem persists.
        • ErrorDescription
          Only present if the Result is "ERROR". Detailed description for "ErrorType".
        • Payout
          Sell price. It will match the bid agreed upon at the Ping phase.
        • LeadID
          Only present if the Result is "OK". Lead ID in Contactability system. For reference only.

        Example Post Response XML - http://dev.contactability.com/ping_post/v1/docs/post_response.xml

    5. Legs Ping Lead API
      1. API request
        Back to Contents

        This API endpoint is used to send leads to Contactability to receive our bids on individual legs that we are interested in buying.

        This API is identical to Ping API with the exception of different URL and API response. Ping response will include individual legs that we are interested in purchasing along with the payout for each leg.

        Each leg will have carrier name, license number (in case of independent only), leg id (unique leg identifier in Contactability system) and payout for that leg.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/ping/legs

        HTTP POST parameter:

        • xml (string)
          • UTF-8 encoded XML string. Must be in accordance with the Contactability Ping XML schema. Failure to do so will result in 4xx "Bad Request" error.

        Example Legs Ping XML - http://dev.contactability.com/ping_post/v1/docs/sample_auto.xml

      2. Legs Ping API response
        Back to Contents

        Ping API will return HTTP response code 200 for all successful ping requests. In case of data errors 4xx response code is returned. In case of service outage or any other server errors on Contactability side, a 5xx HTTP response code is returned.

        In case of data validation errors (4xx), more detailed information about the error will be returned under "ErrorType" and "ErrorDescription" XML elements.

        Each leg will have carrier name, license number (in case of independent only), leg id (unique leg identifier in Contactability system) and payout for that leg.

        API response XML elements:

        • Result
          It will be either "OK" or "ERROR".
        • ErrorType
          Only present if the Result is "ERROR". Values -
          • Auth Failure - Indicating partner specific info is missing or wrong.
          • Bad Request - Data validation errors.
          • Duplicate - For both duplicate ping and post.
          • Timeout - When attempting to post the lead 5 mins after generating PingID.
          • Server Error - Some error occurred on Contactability side. Please reach out to us at support@contactability if the problem persists.
        • ErrorDescription
          Only present if the Result is "ERROR". Detailed description for "ErrorType".
        • Payout
          Contactability's total bid for all legs combined.
        • PingID
          Only present if the Result is "OK". To be used when posting lead to Post lead API.
        • Legs
          Contains individual legs and their payouts.

        Example Legs Ping Response XML - http://dev.contactability.com/ping_post/v1/docs/ping_legs_response.xml

    6. Legs Post Lead API
      1. API request
        Back to Contents

        This API endpoint is used to sell legs of the lead to Contactability after they have been successfully bid upon during legs Ping phase.

        Affiliates can choose to sell us the select number of legs or all the legs that we are interested in buying.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/post/legs

        HTTP POST parameter:

        • ping_id (string)
          A string for the PingID returned by previous successful call to legs Ping lead API.
        • xml (string)
          UTF-8 encoded XML string. Must be in accordance with the Contactability Post XML schema. Failure to do so will result in 4xx "Bad Request" error.

        Example Legs Post XML - http://dev.contactability.com/ping_post/v1/docs/sample_auto_post_legs.xml

      2. Legs Post API response
        Back to Contents

        Ping API will return HTTP response code 200 for all successful ping requests. In case of data errors 4xx response code is returned. In case of service outage or any other server errors on Contactability side, a 5xx HTTP response code is returned.

        In case of data validation errors (4xx), more detailed information about the error will be returned under "ErrorType" and "ErrorDescription" XML elements.

        If accepted, the response will have payout equal to the sum of payouts of individual legs sold to us.

        API response XML elements:

        • Result
          It will be either "OK" or "ERROR".
        • ErrorType
          Only present if the Result is "ERROR". Values -
          • Auth Failure - Indicating partner specific info is missing or wrong.
          • Bad Request - Data validation errors.
          • Duplicate - For both duplicate ping and post.
          • Timeout - When attempting to post the lead 5 mins after generating PingID.
          • Server Error - Some error occurred on Contactability side. Please reach out to us at support@contactability if the problem persists.
        • ErrorDescription
          Only present if the Result is "ERROR". Detailed description for "ErrorType".
        • Payout
          Sell price. Equal to the sum of payouts of individual legs sold to us.
        • LeadID
          Only present if the Result is "OK". LeadID under Contactability. For reference only.

        Example Post Response XML - http://dev.contactability.com/ping_post/v1/docs/post_response.xml

    7. Calls API
      1. API request
        Back to Contents

        This API endpoint is used to query our calls API for sending calls to us. It is a simple HTTP GET request with some required and optional parameters. We will respond with the individual leg (service provider) along with payout (for qualified call) and transfer number.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/calls/ping

        HTTP GET parameters:

        • token (required)
          Authentication token assigned to you by Contactability. Without proper token, it will result in 403 forbidden error.
        • zip (required)
          5 digit zip code of the consumer.
        • phone_hash (required)
          SHA-256 hash of 10-digit consumer phone.
          For example, SHA-256 hash of '8773237750' = 'afbda374f57b608ebe2ed86bc32426c3d97892fd4d9b35b272d5543d146ca234'.
          You can also use the online tool here. SHA-256 is one way encryption meaning it can not be decrypted to actual phone number (Wiki). We use it to not bid on dupes or some other business logic.
        • lead_type_id (required)
          Lead type ID for the call. (1-Auto, 2-Home, 3-Health, 4-Life, 5-Renters, 6-Condo, 7-Commercial, 10-Medicare)
        • insured (optional but recommended)
          Is the consumer is currently insured? (values could be 1 or 0)
        • insurance_company (optional)
          Current insurance company of the consumer if the consumer is currently insured. Refer to the list here
        • continuous_insurance (optional but recommended)
          How long is the consumer currently insured? Values - Less than 12 months, 1-5 Years, More than 5 Years
        • birth_date (optional but recommended)
          Date of birth of the consumer (mm/dd/yyyy). Required for Health and Life types.
        • accidents (optional but recommended)
          For Auto type only. Any accidents in the last 3 years? (values could be 1 or 0)
        • sr_22 (optional but recommended)
          For Auto type only. Does the consumer require SR-22? (values could be 1 or 0)
        • dui (optional but recommended)
          For Auto type only. Any DUI in the last 3 years? (values could be 1 or 0)
        • preexisting_conditions (optional)
          For Health and Life type only. Any pre-existing conditions? (values could be 1 or 0)
        • home_claims (optional)
          For Home type only. Any home claims for the last 5 years? (values could be 1 or 0)
        • requested_coverage (optional)
          For Auto insurance only. Type of coverage the consumer is looking for. Expected values are - Standard, Basic, Superior, Minimum
        • household_income (optional but recommended)
          Household income. Expected values are (send integers like 1,2 etc.) - ("Below $17,000" => 1), ("$17,000 - $20,000" => 2), ("$20,000 - $25,000" => 3), ("$25,000 - $30,000" => 4), ("$30,000 - $35,000" => 5), ("$35,000 - $40,000" => 6), ("$40,000 - $55,000" => 7), ("Over $55,000" => 8)
        • dental_only (optional)
          Whether the consumer is looking for Dental only quote. Expected values are 0 (no) or 1 (yes)
        • medicaid (optional)
          Whether the consumer is looking for medicaid quote. Expected values are 0 (no) or 1 (yes)
        • medicare_advantage (optional)
          Whether the consumer is looking for medicare advantage quote. Expected values are 0 (no) or 1 (yes)
        • medicare_part_a_b (optional)
          Whether the consumer is looking for medicare part A & B quote. Expected values are 0 (no) or 1 (yes)
        • military_affiliation (optional but recommended)
          Military affiliation. Expected values are 0 (no) or 1 (yes)
        • num_vehicles (optional)
          Number of vehicles (For auto insurance only). Number from 1 to 5.
        • own_home (optional but recommended)
          Whether the consumer owns home. Expected values are 0 (no) or 1 (yes)
        • education (optional)
          Highest Education completed. Expected values are (send integers like 1, 2 etc) - ('Less than High School' => 1, ('Some or No High School' => 2), ('High School Diploma' => 3), ('Some College' => 4), ('Associate Degree' => 5), ('Bachelors Degree' => 6), ('Masters Degree' => 7), ('Doctorate Degree' => 8), ('Other' => 0)
        • subsidy_help (optional)
          Whether the consumer needs subsidy. Expected values are 0 (no) or 1 (yes)
        • commercial_coverage (optional)
          For Commercial type only. Type of commercial coverage the consumer is looking for. Values could be - 1 (Commercial Auto), 2 (Commercial Property), 3 (Commercial Business Owners Property), 4 (General Liability), 5 (Worker's Comp)
        • test (optional)
          Pass 1 for testing.

        Example API Call - http://staging.pingpost.contactability.com/api/v1/calls/ping?token=dfgg&zip=43215&lead_type_id=1&insured=1&insurance_company=GEICO&accidents=0&sr_22=0&dui=0&continuous_insurance=More%20than%205%20Years&requested_coverage=Standard&household_income=6&dental_only=0&medicaid=0&medicare_advantage=0&medicare_part_a_b=0&military_affiliation=1&num_vehicles=2&own_home=1&education=7&subsidy_help=0&phone_hash=afbda374f57b608ebe2ed86bc32426c3d97892fd4d9b35b272d5543d146ca234&test=1

      2. Calls API response
        Back to Contents

        We will respond in JSON format with the individual leg (service provider) along with payout (for qualified call) and transfer number.

        • payout
          The payout amount we will pay for the qualified call.
        • service_provider
          Service provider of the buyer.
        • transfer_number
          Transfer number of the buyer.

    8. Clicks API
      1. API request
        Back to Contents

        This API endpoint is used to query our clicks API for sending clicks to us. It is simple REST API using HTTP POST with some required and optional parameters. We will respond with the results matching criterion based on data.

        Staging URL:

        http://staging.pingpost.contactability.com/api/v1/clicks (defaults to JSON format)
        http://staging.pingpost.contactability.com/api/v1/clicks.xml (XML format)
        http://staging.pingpost.contactability.com/api/v1/clicks.json (JSON format)

        HTTP POST parameters:

        • xml (required)
          Lead data in XML format. Please refer to our schema (Lead Schema) for long form data XML format. If you do not have all the info for long form, use our short form per our short form schema. Please note: you may not get any results for short form since we have many filters on our end and we use long form data to match those.
        • zip (required)
          5 digit zip code of the consumer.
        • device_type (optional)
          Device type of the consumer where you will display our ads. Could be "desktop" or "mobile".

        Example XML - http://dev.contactability.com/ping_post/v1/docs/sample_auto.xml

      2. Clicks API response
        Back to Contents

        We will respond with the ads matching criterion based on data from XML.

        • company_name
          Company name for the ad listing.
        • display_name
          Display name for this ad listing.
        • title
          Title of the ad.
        • description
          Description for the ad in HTML format.
        • logo_url
          Logo URL for the ad.
        • site_host
          Site host for the ad.
        • click_url
          Click URL for the ad. This is the URL you will redirect the consumer to after they click on the ad.

  6. API Endpoints
    Back to Contents
  7. Sample XMLs
    Back to Contents