Skip to main content
TrustedForm account holders who are receiving certified leads should use our API to claim the certificate provided with each lead. Doing so verifies the legitimacy of the certificate, stores the certificate for future reference, and provides programmatic access to the information shown on the certificate. To claim a certificate, 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
  • Use the API key provided on the “Settings” tab in the TrustedForm Application and the username ‘API’

​
Reference

When you claim a certificate, you can pass the optional reference parameter. We will store this value along with your claimed certificate. The general idea is that you can pass your lead identifier which will provide a back-reference to the certified lead that you received. This will allow you to know which lead a certificate belongs to, just by examining the certificate data. In the case that your publisher has passed you a two leads with the same Certificate URL, this reference parameter will allow you to determine which lead it was originally passed with. If you are a LeadConduit customer, the LeadConduit Lead URL will be automatically sent as the reference. This allows you to refer back to the lead with which an individual certificate was collected.

​
Vendor

When claiming a certificate, you can pass the optional vendor parameter. We will store this value along with your claimed certificate. Later when you use TrustedForm reporting, you can easily filter or group by vendor. If you use our LeadConduit platform, the vendor will be automatically sent with each certificate claim request.

​
Fingerprints

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 a SHA1 hash of a 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. If you use our LeadConduit platform, the fingerprints will be automatically calculated and sent with each certificate claim request. If you are accessing our API directly, see our instructions for generating a lead fingerprint.

​
Snapshot Scanning

To assist in enforcing compliance, TrustedForm can scan the certificate’s HTML snapshot to ensure specific phrases are (or are not) present. If you scan for required text (disclosure terms, for example), the TrustedForm response will include a warning if that text isn’t found in the snapshot. Alternately, you can scan for forbidden text (disallowed ad copy, for instance), in which case the response will include a warning if the text is found.

​
Scanning for Required Text

To search for required text, pass the search text as the scan parameter when you claim the certificate. 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. If you’d like to search for many different strings, you’ll need to use the parameter array syntax: scan[]=example&scan[]=another%20example. Depending on your setup, you may need to URL encode the square brackets.

​
Scanning for Forbidden Text

To search for forbidden text, use the scan! parameter in the claim call instead. If TrustedForm’s case- and whitespace-insensitive search finds that text in the HTML document, then the message “string found in snapshot” will be given in the warnings key of the claim response. Note that aside from ignoring whitespace and text case, TrustedForm’s scans are literal, including any special characters that you pass. You may include either or both of scan and scan! in a single claim call. You would then need to look for the corresponding messages in the warnings key of the claim response (“string not found in snapshost” or “string found in snapshot”, respectively). As with scanning for required text, you may pass multiple forbidden text scans with the parameter array syntax: scan![]=example&scan![]=another%20example. Again, depending on your setup, you may need to URL encode the square brackets.

​
Masked Certificates

A masked certificate is generated for every claim. You can obtain the URL to it from the masked_cert_url field of the response JSON when you claim a certificate. You can then share it with your buyers. They can claim it using the same claiming instructions as a normal certificate.

​
Response Codes

  • If you successfully claim a certificate, an HTTP 201 Created will be returned with the JSON representation of the certificate in the response body. Beware that using an HTTP GET will also return an HTTP 200 along with the HTML representation of the certificate — your cert will not be claimed with an HTTP GET.
  • If the certificate is older than 3 days or if the certificate URL is invalid, then an HTTP 404 Not Found will be returned.
  • If you have not authenticated correctly using your API key, an HTTP 403 Forbidden will be returned.
If you receive any response code other than those above, please let us know.

​
Pings (Deprecated)

When you ping a certificate, you are requesting profile information about that particular TrustedForm Certificate. See Ping documentation for additional information on utilizing the ping method.

​
Claims

When you claim a certificate, a claim record is created and stored in TrustedForm and the JSON response body contains claim record. See Claim documentation for additional information on claim records.