Bright Horizons Media API - Integration Docs

Debt Leads

The Debt Settlement Leads endpoint allow you as a Publisher to post Debt Settlement leads directly to Bright Horizons Media. Leads sent to the API use the POST method and require both credentials and your Publisher to be enabled for posting leads. Leads are posted in JSON format.

Allowed Days/Times:

Allowed States:

Method	Endpoint	Endpoint Type
Ping	https://api.brighthorizonsmedia.com/ping/debt/full/	JSON
Post	https://api.brighthorizonsmedia.com/post/debt/full/	JSON

PING PARAMETERS (OPTIONAL)

IMPORTANT: Receiving a successful response from the ping (passed:1) does not guarantee the full lead will be purchased when posted.

If the ping was successful, the "passed" parameter will equal 1 (INT) in server response and the "pingid" parameter will contain a string of 49 alphanumeric characters. You do NOT need to post the pingid when posting the full lead.

If the ping was unsuccessful, the "passed" parameter will be set to 0 (INT) and the "pingid" parameter will be empty.

To successfully ping the endpoint, two arrays need to be passed to the JSON endpoint: the xauth[] array and the transaction[] array.

The xauth[] array contains your Publisher ID and the API key assigned by your Account Manager.

The transaction[] array contains the consumer data. The transaction[] array also include an array called finance[] which is where the debt amount is passed.

xauth[] Parameters

Field	Type	Required?	Description
affiliateid	INT	Yes	Your Publisher Id (aka Affiliate Id) provided by your Account Manager
key	CHAR(36)	Yes	The API Key provided by your Account Manager.

transaction[] Parameters

Field	Type	Required?	Description
phone	VARCHAR(16)	Yes	Phone number as provided by the consumer. Can be passed in any format (see following examples) but must be a valid phone number with 10 digits. Examples: 3105551212, 13105551212, (310) 555-1212, 310-555-1212, 310.555.1212.
phonemd5	CHAR(32)	Optional	Optionally, you can pass a MD5 hash of the phone through the phonemd5 parameter instead of the phone parameter. The hash must be of the 10 digit phone number excluding an special characters and/or leading one.
email	STRING	Yes	Email address as provided by the consumer
emailmd5	CHAR(32)	Optional	Optionally, you can pass a MD5 hash of the email address through the emailmd5 parameter instead of the email parameter. The hash must be generated using a lowercased email address. Posts could be rejected if you use different casing between the ping and the post.
state	CHAR(2)	Yes	The State as provided by the consumer (or looked up by zip code).
statemd5	CHAR(32)	Optional	Optionally, you can pass a MD5 hash of the state through the statemd5 parameter instead of the state parameter. The hash must be generated using an uppercased 2 letter state abbreviation. Posts could be rejected if you use different casing between the ping and the post.
zip	CHAR(5)	Yes	The zip code as provided by the consumer. For US zip codes, make sure to include any leading zeros to ensure the zip code has a length of 5 characters.
zipmd5	CHAR(32)	Optional	Optionally, you can pass a MD5 hash of the 5 digit zip code through the zipmd5 parameter instead of the zip parameter. The hash must be generated using only the 5 digit zip code (not including +4). Posts could be rejected if you use different zip codes between the ping and the post.
finances	ARRAY	Yes	The finances parameter is an array containing key => value pairs of data related to the consumer's finances. All fields are required. unsecureddebtamount (INTEGER) - the estimated unsecured debt value as provided by consumer (example: 14750) pretaxincome (INTEGER) - the consumer's pre-tax annual income as provided by the consumer (example: 35000)
trustedformcertid	CHAR(69)	Yes	The full TrustedForm Cert URL. For example, https://cert.trustedform.com/c667435837eZZZ1ccdZXXX885b5ffc997e00f84c1.

SAMPLE PING REQUEST


POST /ping/debt/full/ HTTP/1.1
Host: https://api.brighthorizonsmedia.com
Content-Type: application/json; charset=utf-8
Content-Length: 327

{
	"xauth":
	{
		"affiliateid": 123456,
		"key": "8526df83-yy6u-fg7k-3d4f-3d4b9m2z3bb9"
	},
	"transaction":
	{
		"phone": "7025551212",
		"email": "jjmcclure@example.com",
		"state": "NV",
		"zip": "89002",
		"finances":
		{
			"unsecureddebtamount": 14500,
			"pretaxincome": 35000
		},
		"trustedformcertid": "https://cert.trustedform.com/ZZZWW8ba26XX85bXX16d3cb6c44cc30a7da48ba1"      
	}
}

SAMPLE PING REQUEST USING MD5 PARAMETERS


POST /ping/debt/full/ HTTP/1.1
Host: https://api.brighthorizonsmedia.com
Content-Type: application/json; charset=utf-8
Content-Length: 430

{
	"xauth":
	{
		"affiliateid": 123456,
		"key": "8526df83-yy6u-fg7k-3d4f-3d4b9m2z3bb9"
	},
	"transaction":
	{
		"phonemd5": "f8680683f0bf51aa0925c80c1e8290b4",
		"emailmd5": "459c33c8b07aa277c06061366689d2bb",
		"statemd5": "3e8d115eb4b32b9e9479f387dbe14ee1",
		"zipmd5": "332e7c04d4b04597a1e1417b13e88a7e",
		"finances":
		{
			"unsecureddebtamount": 14500,
			"pretaxincome": 35000
		},
		"trustedformcertid": "https://cert.trustedform.com/ZZZWW8ba26XX85bXX16d3cb6c44cc30a7da48ba1"      
	}
}

SAMPLE PING RESPONSE


{
	"validated":1,
	"passed":1
	"pingid":"ZZZZZZZZ-d7ac-401a-4248-835d-5207c77e67dc",
	"disposition":"",
	"messages":[],
	"errors":[]
}

POST PARAMETERS

To successfully post Debt Settlement leads, two arrays need to be passed to the JSON endpoint: the xauth[] array and the transaction[] array.

The xauth[] array contains your Publisher ID and the API key assigned by your Account Manager.

The transaction[] contains all the details about the lead (first name, last name, email, consumer IP, etc.).

xauth[] Parameters

Field	Type	Required?	Description
affiliateid	INT	Yes	Your Publisher Id (aka Affiliate Id) provided by your Account Manager
key	STRING (36)	Yes	The API Key provided by your Account Manager.

transaction[] Parameters

Field	Type	Required	Description
firstname	STRING	Yes	First name as provided by the consumer
lastname	STRING	Yes	Last name as provided by the consumer
phone	VARCHAR(16)	Yes	Phone number as provided by the consumer. Can be passed in any format (see following examples) but must be a valid phone number with 10 digits. Examples: 3105551212, 13105551212, (310) 555-1212, 310-555-1212, 310.555.1212.
email	STRING	Yes	Email address as provided by the consumer
address	STRING	Optional	Street address as provided by the consumer
address2	STRING	Optional	Street address as provided by the consumer
city	STRING	Optional	City as provided by the consumer. If not provided, we will map the city based on the zip code provided.
state	CHAR(2)	Yes	The State as provided by the consumer (or looked up by zip code).
zip	CHAR(5)	Yes	The zip code as provided by the consumer. For US zip codes, make sure to include any leading zeros to ensure the zip code has a length of 5 characters.
finances	ARRAY	Yes	The finances parameter is an array containing key => value pairs of data related to the consumer's finances. All fields are required. unsecureddebtamount (INTEGER) - the estimated unsecured debt value as provided by consumer (example: 14750) pretaxincome (INTEGER) - the consumer's pre-tax annual income as provided by the consumer (example: 35000) debttype (VARCHAR(64)) - a string of text noting the type of debt the consumer has (example: credit cards, medical)
ip	STRING	Yes	The IP address of the consumer when the form was submitted on your website (not your server IP address). Can be either IPV4 or IPv6.
source	STRING	Yes	The fully qualified URL (or domain) of the webpage where the lead was generated (excluding any query string parameters)
trustedformcertid	CHAR(69)	Yes	The full TrustedForm Cert URL. For example, https://cert.trustedform.com/c667435837eZZZ1ccdZXXX885b5ffc997e00f84c1.
sub1	STRING	Yes	Additional field for tracking purposes
sub2	STRING	Optional	Additional field for tracking purposes
sub3	STRING	Optional	Additional field for tracking purposes
sub4	STRING	Optional	Additional field for tracking purposes
sub5	STRING	Optional	Additional field for tracking purposes

POST REQUESTS & RESPONSES

SAMPLE REQUEST


POST /post/debt/full/ HTTP/1.1
Host: https://api.brighthorizonsmedia.com
Content-Type: application/json; charset=utf-8
Content-Length: 501

{
	"xauth":
	{
		"affiliateid": 123456,
		"key": "8526df83-yy6u-fg7k-3d4f-3d4b9m2z3bb9"
	},
	"transaction":
	{
		"firstname": "JJ",
		"lastname": "McClure",
		"phone": "7025551212",
		"email": "jjmcclure@example.com",
		"address": "",
		"address2": "",
		"city": "Boulder City",
		"state": "NV",
		"zip": "89002",
		"finances":
		{
			"unsecureddebtamount": 14500,
			"pretaxincome": 35000,
			"debttype": "credit cards, medical"
		},
		"ip": "192.168.168.1",
		"source": "yourdomain.com",
		"trustedformcertid": "https://cert.trustedform.com/ZZZWW8ba26XX85bXX16d3cb6c44cc30a7da48ba1",       
		"sub1": "your sub id",
		"sub2": "",
		"sub3": "",
		"sub4": "",
		"sub5": ""        
	}
}

SAMPLE RESPONSE

When a Debt Settlement lead is posted to us, a JSON response will be returned containing useful information about whether the lead was accepted and any additional information we can provide. Below is an example of a successful response.

A response with sold = 1 (or "sold":1) means the lead was accepted by a buyer and is billable. Sold = 0 (or "sold":0) is NOT billable.

The "accepted" parameter is not to be used for determining whether a lead is billable.


{
	"validated": 1,
	"accepted": 1,
	"sold": 1,
	"disposition": "SOLD",
	"messages": [],
	"errors": [],    
	"transactionid": 123456789,
	"leadid": 123456789
}

FAILED RESPONSE

If the request failed, the response will include an errors object which may contain 1 or more messages/errors. This example will return an errors because the unsecureddebtamount value was not passed. Reminder, we do not log or record leads in our system that could not be validated.


{
	"validated": 0,
	"accepted": 0,
	"sold": 0,
	"disposition": ,
	"messages": [
		"Debt Lead could not be validated"
	],
	"errors":
	[
		[
			"Unsecured Debt Amount (required): can not be empty and must INT"
		]
	]
}