v1

latestOpenAPI 3.0.02026-07-2272351.3 KB

Retrieving Insights

Retrieve Certificate Insights

Account holders using TrustedForm Insights who are receiving certified leads can use the following request to retrieve TrustedForm metadata for the lead contained in a TrustedForm certificate.

post/{cert_id_}

Path parameters

cert_id_string required

Certificate ID

Request body

emailstring

When using the data service on a certificate, you may pass an optional email (or email_1, email_2, etc) parameter. TrustedForm will extract the email value and perform fingerprinting against the available data.

fingerprintstring

Calculated lead fingerprint values using the email and phone number received in the lead data accompanying the certificate. Each fingerprint value is an SHA1 hash of an email or phone value. Each fingerprint value should be provided in a fingerprint parameter.

If none of the fingerprints you provide match a fingerprint collected on the certificate, then "none of the provided fingerprints match" will be included in the warnings field and outcome will be "failure". This indicates that the lead data collected on the form does not match the lead data that you received.

forbidden_scan_termsstring

Use this parameter to perform a scan of the page for text that must not be present. TrustedForm will then perform a case and whitespace insensitive search for the string. If the string is found in the HTML document, then "string found in snapshot" will be included in the warnings key of the response and the outcome with be "failure".

This parameter may be included multiple times

forbidden_scan_terms[]string[]

This parameter may be included multiple times

phone_1string

When using the data service on a certificate, you may pass an optional phone (or phone_1, phone_2, etc) parameter. TrustedForm will extract the phone number value and perform fingerprinting against the available data.

required_scan_termsstring

Use this parameter to perform a scan of the page for required text. TrustedForm will then perform a case and whitespace insensitive search for the string. If the string is not found in the HTML document, then "string not found in snapshot" will be included in the warnings key of the response and the outcome will be "failure".

This parameter may be included multiple times

required_scan_terms[]string[]

This parameter may be included multiple times

scan_delimiterstring

You can provide your own delimiter to use when wrapping wildcards or tempate variablies. Your choice of delimiter must be homogeneous (i.e. the beginning and end are the same character(s)), such as |, ==, or |||.

Example request

{
  "email": "user@example.com",
  "fingerprint": "Y6cQVpJhoks3ZidbcADOjXsy4vc=",
  "forbidden_scan_terms": "I do not agree to the terms of service",
  "phone_1": "5125551234",
  "required_scan_terms": "I agree to the terms of service"
}

Response

Success

is_maskedboolean required

A boolean indicating whether the certificate is masked

outcome'success' | 'failure' | 'error' required

The result of the attempt to verify consent. Success indicates that the request did not generate any warnings related to consent verification. Failure indicates that the requests generated warnings because no fingerprints matched, forbidden scan terms were found or required scan terms were missing. Error indicates that the request was not successfull and the request should be reviewed and potentially retried.

reasonstring

Provides an explanation for failure or error.

Only used for outcome of failure or error.

warningsstring[]

An array of strings indicating possible issues with the certificate

none of the provided fingerprints match: No fingerprints matched.
string not found in snapshot: A required page scan text was not found.
string found in snapshot: A forbidden page scan text was found.

Example response

{
  "cert": {
    "age_seconds": 33,
    "approx_ip_geo": {
      "city": "Austin",
      "country_code": "US",
      "lat": 30.4548,
      "lon": -97.7664,
      "postal_code": "78729",
      "state": "TX",
      "time_zone": "America/Chicago"
    },
    "browser": {
      "full": "Chrome 95.0.4638.69",
      "name": "Chrome",
      "version": {
        "full": "95.0.4638.69",
        "major": "95",
        "minor": "0",
        "patch": "4638.69"
      }
    },
    "created_at": "2021-11-12T22:06:44Z",
    "domain": "example.com",
    "event_duration_ms": 21110,
    "expires_at": "2021-11-15T22:06:44Z",
    "form_input_method": [
      "typing",
      "autofill"
    ],
    "ip": "8.8.8.8",
    "is_framed": true,
    "is_mobile": false,
    "kpm": 68.2314,
    "operating_system": {
      "full": "Mac OS X 10.15.7",
      "name": "Mac OS X",
      "version": {
        "full": "10.15.7",
        "major": "10",
        "minor": "15",
        "patch": "7"
      }
    },
    "page_id": "5d8ce3c9502b426f77001ae7",
    "page_url": "https://www.example.com/contact.html",
    "parent_page_url": "https://www.example.com/index.html",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.69 Safari/537.36",
    "wpm": 77.1234
  },
  "fingerprints": {
    "matching": [
      "c4a8e7fe184993964ae81380e91579015306838a",
      "d511850d569bcd7802c30f54de34bb9f2b31eede"
    ],
    "non_matching": [
      "d511850d569bcd7802c30f54de34bb9f2b31eed1"
    ]
  },
  "is_masked": false,
  "outcome": "success",
  "scans": {
    "forbidden_found": [
      "Enim sit amet venenatis"
    ],
    "forbidden_not_found": [
      "Est velit egestas"
    ],
    "required_found": [
      "lorem ipsum dolor"
    ],
    "required_not_found": [
      "Ad qui aperiri"
    ]
  },
  "warnings": []
}