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.

Request
path Parameters
cert_id
required
string

Certificate ID

Request Body schema: application/json
optional

DataServiceRequest

email
string

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.

fingerprint
string

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_terms
string

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[]
Array of strings

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

phone_1
string

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_terms
string

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[]
Array of strings

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

scan_delimiter
string

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

Responses
200

Success

400

Malformed Certificate URL

401

Unauthorized

402

Account is inactive or out of funds

404

TrustedForm certificate has expired or could not be found

405

Attempted to claim a 'sandboxed' certificate

422

The certificate has been claimed too many times

post/{cert_id }
Request samples
application/json
{
  • "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 samples
application/json
{
  • "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": [ ]
}