TCPA Guardian (3rd Party) API
- 23 Mar 2023
- 13 Minutes to read
-
DarkLight
TCPA Guardian (3rd Party) API
- Updated on 23 Mar 2023
- 13 Minutes to read
-
DarkLight
Article Summary
Share feedback
Thanks for sharing 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, | <result>3</result> |
| "capture_rule": 1, | </tcpa> |
| "stored": 1, | <result>3</result> |
| "stored_rule": 1, | </leadid> |
| "result": 3 | <result>3</result> |
| }, | </market> |
| "result": 3 | <result>1</result> |
| }, | <token>{LeadiD Token</token> |
| "result": 3 | </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, | <result>2</result> |
| "capture_rule": 1, | </tcpa> |
| "stored": 1, | <result>2</result> |
| "stored_rule": 1, | </leadid> |
| "result": 2 | <result>2</result> |
| }, | </market> |
| "result": 2 | <result>1</result> |
| }, | <token>{LeadiD Token}</token> |
| "result": 2 | |
| }, | |
| "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:
|
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. |
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 |
| result | Int | 1 |
Was this article helpful?
