TCPA Guardian (3rd Party) API
- 07 Nov 2024
- 24 Minutes to read
- Print
- DarkLight
TCPA Guardian (3rd Party) API
- Updated on 07 Nov 2024
- 24 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Introduction
TCPA Guardian is a REST API call that relies on a unique LeadiD token that is generated by our javascript snippet to witness the consumer's experience as they move through a lead funnel. The responses in this request are derived data insights gathered from the lead event.
Example Request Structure (GET method)
https://api.leadid.com/SingleQuery?lac={ACCOUNTCODE}&id={LEADIDTOKEN}&lak={AUDITKEY}&lpc={PROVIDERCODE}&data={DATA}
Parameter Definitions
Name | Value | Required | Description |
URL | https://api.leadid.com/SingleQuery? | Yes | The URL to be used for the query. |
Method | GET or POST | Yes | The HTTPS method to be used. |
lac | xxxxxxxx-xxxx-xxxx-xxxx | Yes | Your Jornaya Account Code. |
id | 36 Character LeadiD token | Yes | The LeadiD token |
lak | xxxxxxxx-xxxx-xxxx-xxxx | Yes | The Audit Key for this query |
lpc | Alphanumeric string | Yes | A value that identifies the Provider from whom you received this lead. |
data | Pipe | Separated Data with field data labels delimited by semicolons. e.g., email;joe@smith.com|f_name;joe | Yes | The data for which you want to determine Data Integrity. Note: a list of Data Integrity Field Data Labels can be found at the end of this document. |
recordid | Integer or string | When applicable | This is the Lead Management System’s or destination system’s unique identifier for the specific lead record. |
format | json, xml | No | The format in which you would like the data returned. The default value is JSON. |
agency | xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx | When applicable | The agency parameter allows a company that is an AOR or LMS for a client to perform queries on behalf of that client and identify itself accordingly by passing in its own Account Code. |
Security for Usage
The usage of HTTPS/TLS is highly recommended when implementing the Jornaya TCPA Guardian (3rd Party) API. This ensures data transmitted between your networks and Jornaya’s systems are securely encrypted and protected. Jornaya supports the usage and configuration of TLS 1.2, and the following TLS cipher suites:
ECDHE-ECDSA-AES128-GCM-SHA256 | ECDHE-RSA-AES256-SHA384 |
ECDHE-RSA-AES128-GCM-SHA256 | ECDHE-RSA-AES256-SHA |
ECDHE-ECDSA-AES128-SHA256 | ECDHE-ECDSA-AES256-SHA |
ECDHE-RSA-AES128-SHA256 | AES128-GCM-SHA256 |
ECDHE-ECDSA-AES128-SHA | AES128-SHA256 |
ECDHE-RSA-AES128-SHA | AES128-SHA |
ECDHE-ECDSA-AES256-GCM-SHA384 | AES256-GCM-SHA384 |
ECDHE-RSA-AES256-GCM-SHA384 | AES256-SHA256 |
ECDHE-ECDSA-AES256-SHA384 |
Revisions
At any future time, Jornaya may revise the list of supported TLS protocols and cipher suites as required by industry security best practices. You will be notified in advance of such changes to ensure continued successful operations of your integrations with Jornaya’s services.
Example Response Structure
The sample output listed below shows an instance when the TCPA disclosure found on the web form matched the disclosure text entered in the audit profile ('disclosure' = 1).
JSON | XML |
|---|---|
audit: { | <audit> |
"authentic": 1, | <authentic>1</authentic> |
"reg_rule": 1, | <reg_rule>1</reg_rule> |
"call_center": 1, | <call_center>1</call_center> |
"call_center_rule": 1, | <call_center_rule>1</call_center_rule> |
"data_integrity_passed": [ | <data_integrity_passed>1234567890</data_integrity_passed> |
"1234567890" | <data_integrity_default>JONNY</data_integrity_default> |
], | <data_integrity_default>BRAVO</data_integrity_default> |
"data_integrity_default": [ | <data_integrity_default>123</data_integrity_default> |
"JONNY", | <data_integrity_default>456</data_integrity_default> |
"BRAVO", | <data_integrity_default>7890</data_integrity_default> |
"123", | <data_integrity_default>123@TEST.COM</data_integrity_default> |
"456", | <data_integrity>3</data_integrity> |
"7890", | <data_integrity_rule>1</data_integrity_rule> |
"123@TEST.COM" | <fields> |
], | <f_name>3</f_name> |
"data_integrity": 3, | <l_name>3</l_name> |
"data_integrity_rule": 1, | <phone1>1</phone1> |
"fields": { | <email>3</email> |
"f_name": 3, | </fields> |
"l_name": 3, | <market> |
"phone1": 1, | <leadid> |
"email": 3 | <tcpa> |
}, | <disclosure>1</disclosure> |
"market": { | <consent>3</consent> |
"leadid": { | <prominence>2</prominence> |
"tcpa": { | <contrast>1</contrast> |
"disclosure": 1, | <visibility>1</visibility> |
"consent": 3, | <type>1</type> |
"prominence": 2, | <prominence_value>37.5</prominence_value> |
"contrast": 1, | <contrast_value>83.080344452465</contrast_value> |
"visibility": 1, | <visibility_value>55.816779887122</visibility_value> |
"type": 1, | <prominence_rule>2</prominence_rule> |
"prominence_value": 37.5, | <contrast_rule>1</contrast_rule> |
"contrast_value": 83.080344452465269, | <visibility_rule>1</visibility_rule> |
"visibility_value": 55.816779887122181, | <disclosure_rule>1</disclosure_rule> |
"prominence_rule": 2, | <consent_rule>3</consent_rule> |
"contrast_rule": 1, | <type_rule>1</type_rule> |
"visibility_rule": 1, | <capture>1</capture> |
"disclosure_rule": 1, | <capture_rule>1</capture_rule> |
"consent_rule": 3, | <stored>1</stored> |
"type_rule": 1, | <stored_rule>1</stored_rule> |
"capture": 1, | <brand_names> |
"capture_rule": 1, | <brand_name>Brand Name 1</brand_name> |
"stored": 1, | <brand_name_present>1</brand_name_present> |
"stored_rule": 1, | <brand_name_present_rule>1</brand_name_present_rule> |
"brand_names": [ | <brand_name_consent>1</brand_name_consent> |
{ | <brand_name_consent_rule>1</brand_name_consent_rule> |
"brand_name": "brand name 1", | </brand_names> |
"brand_name_present": 1, | <brand_names> |
"brand_name_present_rule": 1, | <brand_name>Brand Name 2</brand_name> |
"brand_name_consent": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_consent_rule": 1, | <brand_name_present>0</brand_name_present> |
}, | <brand_name_present>0</brand_name_present> |
{ | <brand_name_present>0</brand_name_present> |
"brand_name": "Brand name 2", | </brand_names> |
"brand_name_present": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_present_rule": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_consent": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_consent_rule": 1, | <brand_name_present>0</brand_name_present> |
}, | <brand_name_present>0</brand_name_present> |
"brand_name": "Brand name 3", | </brand_names> |
"brand_name_present": 1, | <brand_names> |
"brand_name_present_rule": 1, | <brand_name_consent>0</brand_name_consent> |
"brand_name_consent": 4, | <brand_name_consent_rule>2</brand_name_consent_rule> |
"brand_name_consent_rule": 3, | </brand_names> |
} | <topical_relevance> |
], | <keyword>Keyword 1</keyword> |
"topical_relevance": [ | <keyword_present>1</keyword_present> |
"keyword": "Keyword 1", | <keyword_present_rule>1</keyword_present_rule> |
"keyword_present": 1 | </topical_relevance> |
"keyword_present_rule": 1 | <topical_relevance> |
}, | <keyword>Keyword 2</keyword> |
{ | <keyword_present>1</keyword_present> |
"keyword": "Keyword 2", | <keyword_present_rule>1</keyword_present_rule> |
"keyword_present": 1 | </topical_relevance> |
"keyword_present_rule": 1 | <result>3</result> |
} | </tcpa> |
], | <result>3</result> |
"result": 3 | </leadid> |
}, | <result>3</result> |
"result": 3 | </market> |
}, | <result>1</result> |
"result": 3 | <token>{LeadiD Token}</token> |
}, | </audit> |
"result": 1, | |
"token": "{LeadiD Token}" | |
} |
The sample output listed below shows an instance when either (a) TCPA disclosure is not found on the web form ('disclosure' = 0), or (b) the TCPA disclosure identified on the web form does not match the disclosure text entered in the audit profile ('disclosure' = 2).
JSON | XML |
|---|---|
"audit": { | <audit> |
"authentic": 1, | <authentic>1</authentic> |
"reg_rule": 1, | <reg_rule>1</reg_rule> |
"call_center": 1, | <call_center>1</call_center> |
"call_center_rule": 1, | <call_center_rule>1</call_center_rule> |
"data_integrity_passed": [ | <data_integrity_passed>1234567890</data_integrity_passed> |
"1234567890" | <data_integrity_default>JONNY</data_integrity_default> |
], | <data_integrity_default>BRAVO</data_integrity_default> |
"data_integrity_default": [ | <data_integrity_default>123</data_integrity_default> |
"JONNY", | <data_integrity_default>456</data_integrity_default> |
"BRAVO", | <data_integrity_default>7890</data_integrity_default> |
"123", | <data_integrity_default>123@TEST.COM</data_integrity_default> |
"456", | <data_integrity>3</data_integrity> |
"7890", | <data_integrity_rule>1</data_integrity_rule> |
"123@TEST.COM" | <fields> |
], | <f_name>3</f_name> |
"data_integrity": 3, | <l_name>3</l_name> |
"data_integrity_rule": 1, | <phone1>1</phone1> |
"fields": { | <email>3</email> |
"f_name": 3, | </fields> |
"l_name": 3, | <market> |
"phone1": 1, | <leadid> |
"email": 3 | <tcpa> |
}, | <disclosure>2</disclosure> |
"market": { | <prominence>0</prominence> |
"leadid": { | <contrast>0</contrast> |
"tcpa": { | <visibility>0</visibility> |
"disclosure": 2, | <prominence_rule>2</prominence_rule> |
"prominence": 0, | <contrast_rule>2</contrast_rule> |
"contrast": 0, | <visibility_rule>2</visibility_rule> |
"visibility": 0, | <disclosure_rule>2</disclosure_rule> |
"prominence_rule": 2, | <capture>1</capture> |
"contrast_rule": 2, | <capture_rule>1</capture_rule> |
"visibility_rule": 2, | <stored>1</stored> |
"disclosure_rule": 2, | <stored_rule>1</stored_rule> |
"capture": 1, | <brand_names> |
"capture_rule": 1, | <brand_name>Brand Name 1</brand_name> |
"stored": 1, | <brand_name_present>1</brand_name_present> |
"stored_rule": 1, | <brand_name_present_rule>1</brand_name_present_rule> |
"brand_names": [ | <brand_name_consent>1</brand_name_consent> |
{ | <brand_name_consent_rule>1</brand_name_consent_rule> |
"brand_name": "brand name 1", | </brand_names> |
"brand_name_present": 1, | <brand_names> |
"brand_name_present_rule": 1, | <brand_name>Brand Name 2</brand_name> |
"brand_name_consent": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_consent_rule": 1, | <brand_name_present>0</brand_name_present> |
}, | <brand_name_present>0</brand_name_present> |
{ | <brand_name_present>0</brand_name_present> |
"brand_name": "Brand name 2", | </brand_names> |
"brand_name_present": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_present_rule": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_consent": 1, | <brand_name_present>0</brand_name_present> |
"brand_name_consent_rule": 1, | <brand_name_present>0</brand_name_present> |
}, | <brand_name_present>0</brand_name_present> |
"brand_name": "Brand name 3", | </brand_names> |
"brand_name_present": 1, | <brand_names> |
"brand_name_present_rule": 1, | <brand_name_consent>0</brand_name_consent> |
"brand_name_consent": 4, | <brand_name_consent_rule>2</brand_name_consent_rule> |
"brand_name_consent_rule": 3, | </brand_names> |
} | <topical_relevance> |
], | <keyword>Keyword 1</keyword> |
"topical_relevance": [ | <keyword_present>1</keyword_present> |
"keyword": "Keyword 1", | <keyword_present_rule>1</keyword_present_rule> |
"keyword_present": 1 | </topical_relevance> |
"keyword_present_rule": 1 | <topical_relevance> |
}, | <keyword>Keyword 2</keyword> |
{ | <keyword_present>1</keyword_present> |
"keyword": "Keyword 2", | <keyword_present_rule>1</keyword_present_rule> |
"keyword_present": 1 | </topical_relevance> |
"keyword_present_rule": 1 | <result>2</result> |
} | </tcpa> |
], | <result>2</result> |
"result": 2 | </leadid> |
}, | <result>2</result> |
"result": 2 | </market> |
}, | <result>1</result> |
"result": 2 | <token>{LeadiD Token}</token> |
}, | |
"result": 1, | |
"token": "{LeadiD Token}" | |
} |
Data Responses
The following sections list the responses (and associated values) received when employing Jornaya's TCPA Guardian (3rd Party) during a lead audit. When the TCPA disclosure on the web form matches a disclosure text in the audit profile, all of the TCPA audit responses will be returned.
No Response
Alternatively, if (a) Jornaya is not able to identify a TCPA disclosure on the web form, or (b) the TCPA disclosure on the web form does not match any disclosure text in the audit profile, some responses - denoted with an asterisk (*) - cannot be determined and will not be included in the response.
LeadID Authenticity | ||
|---|---|---|
Data Point | Value | Description |
authentic | 0 | One or more of the conditions have been met below and no additional data will be returned for this LeadiD token:
|
1 | Authentic LeadiD | |
TCPA Disclosure | ||
|---|---|---|
Data Point | Value | Description |
disclosure | 0 | The TCPA disclosure field label was not present during the lead event. |
1 | A matching TCPA disclosure was present on the lead form. | |
2 | The disclosure found on the form does not match a specified TCPA disclosure in the audit profile. | |
disclosure_rule | # | Returned flag color for 'disclosure': 1 - ' Green'; 2 - ' Yellow'; 3 - ' Red' |
TCPA Consent | ||
|---|---|---|
Data Point | Value | Description |
consent* | 0 | Consent is given via form submission. |
1 | Active Consent - The consumer proactively selected the consent option. | |
2 | Passive Consent - Consent was pre-populated for the user. | |
3 | Passive Decline - The consumer did not provide consent and the consent option was not pre-populated. | |
4 | Active Decline - The consumer proactively deselected the consent option. | |
consent_rule* | # | Returned flag color for 'disclosure': 1 - ' Green'; 2 - ' Yellow'; 3 - ' Red' |
TCPA Consent Type | ||
|---|---|---|
Data Point | Value | Description |
type | 0 | No user interaction is required. |
| 1 | Checkbox |
| 2 | Radio button |
| 3 | Yes/No dropdown menu |
type_rule* | # | Returned flag color for 'disclosure': 1 - 'Green'; 2 - 'Yellow'; 3 - 'Red' |
Conspicuousness of Disclosure: Prominence | ||
|---|---|---|
Data Point | Value | Description |
prominence | 0 | The font size of the disclosure is unknown, or when there is no TCPA disclosure match. |
1 | The font size is at least 16 pixels (12pt). | |
2 | The font size is between 9px and 15px (6.75-11 pt). | |
3 | The font size is less than 9px (6.75pt). | |
4 | The disclosure was not visible to the user | |
prominence_value* | ## | A calculated score based on the font size of the disclosure found on the page. The range is from 0-100 where 100 is over 16 pixels and 0 is below 9 pixels. |
prominence_rule | # | Returned flag color for 'disclosure': 1 - 'Green'; 2 - ' Yellow'; 3 - ' Red' |
Conspicuousness of Disclosure: Contrast | ||
|---|---|---|
Data Point | Value | Description |
contrast | 0 | The contrast of the font color to the background color is unknown, or when there is no TCPA disclosure match. |
1 | There is at least a 40% contrast between the text and background colors. | |
2 | There is at least a 25% contrast between the text and background colors. | |
3 | The contrast between the text color and the background color is lower than 25%. | |
4 | The disclosure was not visible to the user. | |
contrast_value* | ## | A calculated rating based on the contrast between the disclosure's font color and the site's background color. The range is from 0- 100 where 100 represents the highest contrast and 0 is the lowest contrast. |
contrast_type | # | Returned flag color for 'disclosure': 1 - ' Green'; 2 - ' Yellow'; 3 - ' Red' |
Conspicuousness of Disclosure: Visibility | ||
|---|---|---|
Data Point | Value | Description |
visibility | 0 | The visibility of the disclosure is unknown, or when there is no TCPA disclosure match. |
1 | The overall visibility of the disclosure is high. (visibility_value > 50) | |
2 | The overall visibility of the disclosure is medium. (visibility_value between 20 and 50) | |
3 | The overall visibility of the disclosure is low. (visibility_value < 20) | |
4 | The disclosure was not visible to the user. | |
visibility_value* | ## | A composite score of the prominence and contrast of the disclosure. The range is from 0-100 where 100 represents the most visible and 0 is the least visible. |
visibility_rule | # | Returned flag color for 'disclosure': 1 - 'Green'; 2 - ' Yellow'; 3 - ' Red' |
Visual Documentation | ||
|---|---|---|
Data Point | Value | Description |
capture | 1 | The Visual Playback has been captured. |
2 | The Visual Playback has been partially captured. | |
0 | The Visual Playback has not been captured. | |
capture_rule | # | Returned flag color for 'disclosure': 1 - ' Green'; 2 - ' Yellow'; 3 - ' Red' |
stored | 1 | The Visual Playback has been stored. |
0 | The Visual Playback has not been stored. | |
stored_rule | # | Returned flag color for 'disclosure': 1 - 'Green'; 2 - ' Yellow'; 3 - ' Red' |
TCPA Result | ||
|---|---|---|
Data Point | Value | Description |
result | # | Overall '_rule' value returned as per flag settings in the Jornaya portal. The 'result' contains the highest number returned in a '_rule' data element, and corresponds to the overall flag color returned in the TCPA section: NOTE: The overall rules does not include the brand name and topical relevance flag results.
|
Data Integrity | ||
|---|---|---|
Data Point | Value | Description |
data_integrity | 0 | Mismatch. The value provided was not matched to any data witnessed by Jornaya during the lead event. |
1 | Match: The value of the data you submitted IS what was actually entered on the lead form. | |
2 | Mismatch With Disclosure: The value of the data you submitted is NOT what was actually entered but may have been changed by the generator. | |
3 | Default Value: The data sent was the default field value. | |
fields | array | Elements, where the key is the field name and the value, is the data_integrity value/outcome (see above). NOTE: email integrity is checked in 3 parts. The complete email is checked. In the event that there is not a match on the complete email address, the data_integrity results for each of these components are also returned in the response. |
data_integrity_failed | array | Array list of data submitted that failed data integrity. |
data_integrity_passed | array | Array list of data submitted that passed data integrity. |
data_integrity_default | array | Array list of data submitted that was the default values. |
Consumer Origin | ||
|---|---|---|
Data Point | Value | Description |
call_center | 1 | Information was entered by a 3rd party. This Data Point is only returned when the campaign that created the LeadiD token was identified as a call center. |
NEW Data Points!
Brand name and Topical Relevance Data Points listed below
Brand Name | ||
|---|---|---|
Data Point | Value | Description |
brand_name | {string_name} | Brand name specified in the audit profile. |
Brand Name Present | ||
|---|---|---|
Data Point | Value | Description |
brand_name_present | 0 | Specified brand was not present in the lead form. |
1 | A matching brand name was present on the lead form. | |
brand_name_present_rule | # | Returned flag color for 'disclosure': 1 - ' Green'; 2 - 'Yellow'; 3 - 'Red' |
Brand Name Consent | ||
|---|---|---|
Data Point | Value | Description |
brand_name_consent | 0 | A checkbox was not present and/or visible next to the brand name in the lead form. |
1 | Active Consent - The consumer proactively checked the checkbox for the brand name. | |
2 | Passive Consent - Consent was pre-populated for the consumer. | |
3 | Passive Decline - Consumer did not provide consent and the checkbox for the brand name was not checked for the user. | |
4 | Active Decline - Consumer proactively unchecked the checkbox for the brand name. | |
brand_name_consent_rule | # | Returned flag color for 'disclosure': 1 - ' Green'; 2 - 'Yellow'; 3 - 'Red' |
Topical Relevance | ||
|---|---|---|
Data Point | Value | Description |
keyword | {string} | Keyword specified in the audit profile. |
keyword_present | 0 | Keyword does not match a specified keyword in the audit profile. |
1 | A matching keyword was present on the lead form. | |
keyword_present_rule | # | Returned flag color for 'disclosure': 1 - ' Green'; 2 - 'Yellow'; 3 - 'Red' |
Audit Result | ||
|---|---|---|
Data Point | Value | Description |
result | # | Overall 'rule' value from the query response, as per flag settings in the Jornaya portal for the Call center and Data Integrity responses:
|
Field Data Labels
The field data label is used to identify the information being sent in the "data" parameter which allows it to be ingested properly.
Example: f_name; Joe
Label | Description |
Note: Data field values are restricted to 250 characters max per value. | |
f_name | First Name |
l_name | Last Name |
phone1 | Phone1 |
phone2 | Phone2 |
address1 | Address1 |
address2 | Address2 |
city | City |
state | State |
zip | Zip |
Error Codes
Value | Description |
100 | Internal Error Retry Jornaya side error. Initiate retry logic. |
1000 | Leadid not set The LeadiD value has not been provided or the HTTPS method (GET or POST) is not in the correct format for the LeadiD value to be set. |
1001 | Malformed LeadiD The LeadiD value is either malformed or blank. |
2000 | Account code not set The Account code value has not been provided. |
2001 | Malformed account code The Account code value is either malformed or blank. |
4001 | Malformed Audit Key The audit key is malformed or blank. |
5000 | Invalid Entry Code The entity code provided is not valid. |
6000 | Invalid Account Code and/or Audit Key Either the account code or audit key provided is invalid. |
7000 | Testing not enabled for account The account is not set up for testing. Please contact support@jornaya.com to have this enabled. |
Response Data Types and Lengths
Data Point | Type | Max Length |
disclosure | Int | 1 |
disclosure_rule | Int | 1 |
consent | Int | 1 |
consent_rule | Int | 1 |
type | Int | 1 |
type_rule | Int | 1 |
prominence | Int | 1 |
prominence_value | Float | 32 bit |
prominence_rule | Int | 1 |
contrast | Int | 1 |
contrast_value | Float | 32 bit |
contrast_rule | Int | 1 |
visibility | Int | 1 |
visibility_value | Float | 32 bit |
visibility_rule | Int | 1 |
capture | Int | 1 |
capture_rule | Int | 1 |
stored | Int | 1 |
stored_rule | Int | 1 |
brand_name | {string} | |
brand_name_present | Int | 1 |
brand_name_present_rule | Int | 1 |
brand_name_consent | Int | 1 |
brand_name_consent_rule | Int | 1 |
keyword | {string} | |
keyword_present | Int | 1 |
keyword_present_rule | Int | 1 |
result | Int | 1 |
Was this article helpful?
