Claiming Certificates

Claiming a Certificate

TrustedForm account holders who are receiving certified leads can use the TrustedForm API to claim the certificate provided with each lead. Doing so

  1. Verifies the legitimacy of the certificate
  2. Stores the certificate for future reference and
  3. Provides programmatic access to the information shown on the certificate

To claim a certificate using the TrustedForm API, send an HTTP POST request to the certificate URL sent by your publisher.

Do not make a request unless the URL starts with https://cert.trustedform.com, otherwise you may expose your TrustedForm credentials to someone else

  • Use a POST request — any other type of request will not claim the certificate
  • Use the Accept: application/json request header
  • Use the Content-Type: application/json or Content-Type: application/x-www-form-urlencoded header, and encode the request body accordingly.
  • In the Authorization header, use the API key provided on the "Settings" tab in the TrustedForm Application and the username 'API'.

Page Scanning

As part of the claiming process, it's often required that certain language either exists or doesn't exist on the page. For example, you may want to ensure certain consent language exists. As another example, you may want to ensure other language does not exist, such as "free iPhone".

Page Scanning Params

You can use the required_scan_terms and forbidden_scan_terms parameters.

  • required_scan_terms: Use this parameter to scan for language you want to ensure exist on the page.
  • forbidden_scan_terms: Use this parameter to scan for language you want to ensure does not exist on the page.

Often, you will want to scan against a variety of possible texts. The TrustedForm Claiming API enables you to do this in three ways:

  1. Send the variations as a list using required_scan_terms[] or forbidden_scan_terms[]
  2. Use wildcards in the consent language.
  3. Use templates.

You can use a mixture of all three.

Wildcards

Use {{*}} in the consent language you wish to scan for as a wildcard. For Example, passing "on behalf of {{*}} at the telephone number" will match "on behalf of Mortgage Acme at the telephone number".

Like using exact language, scans using wildcards can be sent in as an array.

Templating

Templating is different than other versions of page scanning in that you must 1) send it as JSON (i.e. Content-type of application/json); 2) provide a list of key/values to use in the template.

If we were to use the example from above, we might use the following templates:

{
  "required_scan_terms": [
    {
      "template": "on behalf of {{company}} at the telephone number",
      "variables": [
        {"company": "Mortgage Acme"},
        {"company": "Acme Mortgage"},
        {"company": "Acme Co."}
      ]
    },
    {
      "template": "on behalf of {{company}} at the {{contact_method}}",
      "variables": [
        {"company": "Mortgage Acme", "contact_method": "email"},
        {"company": "Acme Mortgage", "contact_method": "fax number"},
        {"company": "Acme Mortgage", "contact_method": "email"},
        {"company": "Acme Co.", "contact_method", "email"}
      ]
    }
  ]
}

Scan Delimiters

When using wildcards in page scans and page scan templates, the default method is to surround the wildcard or template key with "handlebar" braces ({{}}). If that conflicts with your system, you can provide your own delimiter to use. Currently, TrustedForm only allows homogeneous delimiters (i.e. the beginning and end are the same character(s)) such as **, |, or even +++.

Sandboxed Certificates

Certificates created with the sandbox flag set to true cannot be claimed.

Request
path Parameters
cert_id
required
string

Certificate ID

header Parameters
Content-type
required
string

Can be either application/json or application/x-www-form-urlencoded.

Request Body schema: application/json

Claiming Parameters

email
string

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

fingerprints
string

When you claim a certificate you can calculate lead fingerprint values using the email and phone number you 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 at least one of the fingerprints you provide does not match one of those collected on the certificate you will receive the none of the provided fingerprints match in the claim warnings field. This indicates that the lead data collected on the form does not match the lead data that you received.

string or Array of strings or PageScan (object) or Array of PageScan (objects)

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 not found in the HTML document, then "string found in snapshot" will be included in the warnings key of the claim response.

phone
string

When claiming a certificate, you can 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.

reference
string

When you claim a certificate, you can include an optional parameter reference We will store this value in the certificate's claim record. A use case for the reference parameter is to add your unique lead identifier to the claim record, which will provide a reference point from the claim to the certified lead that you received.

This will indicate which lead a certificate belongs to just by examining the certificate data. In the case that your publisher has passed you two leads with the same Certificate URL, this reference parameter will allow you to determine which lead it was originally passed with.

string or Array of strings or PageScan (object) or Array of PageScan (objects)

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

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

vendor
string

When claiming a certificate, you can pass the optional vendor parameter. This is intended for tracking the name of the company that provided the lead associated with the certificate. We will store this value in the certificate’s claim record. When you use TrustedForm reporting, you can easily filter or group by a vendor.

Responses
201

Claim Created Response

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_1": "user@example.com",
  • "forbidden_scan_terms": "I do not agree to the terms of service",
  • "phone_1": "999-999-0909",
  • "reference": "1128238382829",
  • "required_scan_terms": "I agree to the terms of service",
  • "vendor": "Acme Co."
}
Response samples
application/json
{
  • "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": [ ]
}