Introducing LeadSafe

This guide includes essential information about URLs and API endpoints. We recommend using it in conjunction with our Postman collection, which contains working code samples for quick and easy implementation.

Software Environments

LeadSafe uses separate base URLs for its development and production environments. Your account manager will provide you with the base URLs appropriate to your LeadSafe instance. Please see examples below:

Development

https://[YOURPROVIDER].leadsafe-dev.tech

Production

https://[YOURPROVIDER].leadsafe.tech

Note

The appropriate value to substitute for [YOURPROVIDER] will be provided by your account manager

Authentication

The API uses HTTP Basic Auth and you will be provided with separate API Key and Client Secret for both development and production environments. Your credentials will need to be sent alongside each API request.

In your Basic Auth authentication header, use your API Key as your username and your Client Secret as your password.

If you have not received your credentials, please contact your account manager

API Endpoints

Search

This endpoint is used for querying a lead’s SSN to establish if there are any known issues with the customer. The endpoint takes an SSN as input and will return a Red, Amber, Green indicator as a response.

The result variable in the response will always contain one of the following values:

Red
Amber
Green

Endpoint URL:

Development: https://[YOURPROVIDER].leadsafe-dev.tech/leadsafe/search

Production: https://[YOURPROVIDER].leadsafe.tech/leadsafe/search

Sample Request:

{
    "SocialSecurityNumber": "111111222"
}

Sample Response:

{"result":"Green"}

Detailed Search

This endpoint is used for querying a lead’s SSN to establish if there are any known issues with the customer. The endpoint takes an SSN as input and will return a Red, Amber, Green indicator as a response, along with the reason details.

Endpoint URL:

Development: https://[YOURPROVIDER].leadsafe-dev.tech/leadsafe/search-detailed

Production: https://[YOURPROVIDER].leadsafe.tech/leadsafe/search-detailed

Sample Request:

{
    "SocialSecurityNumber": "111111222"
}

Sample Response:

{
    "details": [
        {
            "reason": "RevokePaymentAuth",
            "startDate": "2024-04-02T00:00:00",
            "endDate": null
        }
    ],
    "result": "Red"
}

Add/Update Record

This endpoint is used for adding or updating a user record. Each time one of your customers enters or leaves one of LeadSafe’s status criteria shown in this section, you must make a call to this endpoint to inform us of the change.

Endpoint URL:

Development: https://[YOURPROVIDER].leadsafe-dev.tech/leadsafe/add

Production: https://[YOURPROVIDER].leadsafe.tech/leadsafe/add

Sample Request:

{
    "Records": [
        {
            "EndDate": null,
            "Reason": "RevokePaymentAuth",
            "SocialSecurityNumber": "111111222",
            "StartDate": "2024-04-02"
        }
    ]
}

Reason should be one of the following:

Default	The customer has entered into a default status
RevokePaymentAuth	The customer has revoked ACH permissions
Lawsuit	The customer has instigated a lawsuit
RegulatoryComplaint	The customer has instigated a regulatory complaint
DebtConsolidation	The customer has engaged a debt consolidation agency
SuspectedIdTheft	The customer has reported ID theft
Bankruptcy	The customer has declared bankruptcy
Abusive	The customer is abusive
Deceased	The customer is deceased

StartDate is the date on which the customer entered into the status specified in Reason

EndDate is an optional, nullable field which specifies the date on which the customer left the status specified in Reason

Sample Response:

{
    "code": 100,
    "message": "Records added"
}

CSV Upload

In addition to being able to add and update records via API, we also offer a CSV upload via SFTP mechanism. Your account manager will be able to provide you with SFTP credentials if required.

ClientCode,SocialSecurityNumber,StartDate,EndDate,Reason
exampleco,123456789,2024-01-05,,Default
exampleco,111222333,2024-01-06,2024-02-12,RevokePaymentAuth
exampleco,240120120,2024-01-07,,Lawsuit
exampleco,411411411,2024-01-08,,RegulatoryComplaint
exampleco,910910910,2024-01-09,,DebtConsolidation
exampleco,761789231,2024-01-10,2024-02-19,Default
exampleco,123123123,2024-01-11,,SuspectedIdTheft
exampleco,412421341,2024-01-12,,Bankruptcy