TCPA Guardian (3rd Party) API
  • 10 Jan 2024
  • 13 Minutes to read
  • Dark
    Light

TCPA Guardian (3rd Party) API

  • Dark
    Light

Article Summary

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


NameValueRequiredDescription
URLhttps://api.leadid.com/SingleQuery?
YesThe URL to be used for the query.
MethodGET or POST
YesThe HTTPS method to be used.
lacxxxxxxxx-xxxx-xxxx-xxxx
Yes
Your Jornaya Account Code.
id36 Character LeadiD token
Yes
The LeadiD token.
lakxxxxxxxx-xxxx-xxxx-xxxx
Yes
The Audit Key for this query.
lpcAlphanumeric string
Yes
A value that identifies the Provider from whom you received this lead.
dataPipe | 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 applicableThis is the Lead Management System’s or destination system’s unique identifier for the specific lead record.
format
json, xml
NoThe format in which you would like the data returned. The default value is JSON.
agencyxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxxWhen applicableThe 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-SHA256ECDHE-RSA-AES256-SHA384
ECDHE-RSA-AES128-GCM-SHA256ECDHE-RSA-AES256-SHA
ECDHE-ECDSA-AES128-SHA256ECDHE-ECDSA-AES256-SHA
ECDHE-RSA-AES128-SHA256AES128-GCM-SHA256
ECDHE-ECDSA-AES128-SHAAES128-SHA256
ECDHE-RSA-AES128-SHAAES128-SHA
ECDHE-ECDSA-AES256-GCM-SHA384AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384AES256-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).

JSONXML
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).

JSONXML
 "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
ValueDescription
authentic0One or more of the conditions have been met below and no additional data will be returned for this LeadiD token:
  • This was not a token that Jornaya created.
  • This token has been queried too many times (i.e. hundreds or thousands of times) when Jornaya’s partners performed an API call to our system.
  • This token was created over a year ago. 
  • This token is associated with a consumer who has exercised their CCPA Right to Opt-out.

1Authentic LeadiD


TCPA Disclosure

Data Point
Value
Description
disclosure
0The TCPA disclosure field label was not present during the lead event.

1A matching TCPA disclosure was present on the lead form.

2The 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 PointValueDescription
consent*0Consent is given via form submission.

1Active Consent - The consumer proactively selected the consent option.

2Passive Consent - Consent was pre-populated for the user.

3Passive Decline - The consumer did not provide consent and the consent option was not pre-populated.

4Active 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
type0No user interaction is required.
 1Checkbox
 2Radio button
 3Yes/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
0The font size of the disclosure is unknown, or when there is no TCPA disclosure match.

1The font size is at least 16 pixels (12pt).

2The font size is between 9px and 15px (6.75-11 pt).

3The font size is less than 9px (6.75pt).

4The 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
contrast0The contrast of the font color to the background color is unknown, or when there is no TCPA disclosure match.

1There is at least a 40% contrast between the text and background colors.

2There is at least a 25% contrast between the text and background colors.

3The contrast between the text color and the background color is lower than 25%.

4The 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
ValueDescription
visibility0The visibility of the disclosure is unknown, or when there is no TCPA disclosure match.

1The overall visibility of the disclosure is high. (visibility_value > 50)

2The overall visibility of the disclosure is medium. (visibility_value between 20 and 50)

3The overall visibility of the disclosure is low. (visibility_value < 20)

4The 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
capture1The Visual Playback has been captured.

2The Visual Playback has been partially captured.

0The Visual Playback has not been captured.
capture_rule#Returned flag color for 'disclosure': 1 - ' Green'; 2 - ' Yellow'; 3 - ' Red'
stored1The Visual Playback has been stored.

0The 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:
  • 1 - ' Green'; 2 - ' Yellow'; 3 - ' Red'


Data Integrity

Data Point
Value
Description
data_integrity0Mismatch. The value provided was not matched to any data witnessed by Jornaya during the lead event.

1Match: The value of the data you submitted IS what was actually entered on the lead form.

2Mismatch With Disclosure: The value of the data you submitted is NOT what was actually entered but may have been changed by the generator.

3Default Value: The data sent was the default field value.
fieldsarrayElements, 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
arrayArray list of data submitted that failed data integrity.
data_integrity_passed
arrayArray list of data submitted that passed data integrity.
data_integrity_default
arrayArray list of data submitted that was the default values.


Consumer Origin

Data Point
Value
Description
call_center1Information 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:
  • 1 - ' Green'; 2 - 'Yellow'; 3 - 'Red'


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

LabelDescription
Note: Data field values are restricted to 250 characters max per value.
f_nameFirst Name
l_nameLast Name
emailEmail
phone1Phone1
phone2
Phone2
address1Address1
address2Address2
cityCity
stateState
zipZip


Error Codes


ValueDescription
100Internal Error
Retry Jornaya side error. Initiate retry logic.
1000Leadid 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.
1001Malformed LeadiD
The LeadiD value is either malformed or blank.
2000Account code not set
The Account code value has not been provided.
2001Malformed account code
The Account code value is either malformed or blank.
4001Malformed Audit Key
The audit key is malformed or blank.
5000Invalid Entry Code
The entity code provided is not valid.
6000Invalid Account Code and/or Audit Key
Either the account code or audit key provided is invalid.
7000Testing 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 PointTypeMax Length
disclosureInt1
disclosure_ruleInt
1
consentInt
1
consent_ruleInt
1
typeInt
1
type_ruleInt
1
prominenceInt
1
prominence_value
Float
32 bit
prominence_rule
Int
1
contrastInt
1
contrast_valueFloat
32 bit
contrast_ruleInt
1
visibilityInt
1
visibility_valueFloat32 bit
visibility_ruleInt
1
captureInt
1
capture_ruleInt
1
storedInt
1
stored_ruleInt
1
resultInt
1

Was this article helpful?