TrustedForm account holders who are receiving certified leads can use the TrustedForm 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 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/jsonrequest header
- Use the
Content-Type: application/x-www-form-urlencodedheader, 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', please see the example below
When you claim a certificate, you can pass the optional parameter
reference We will store this value along with your claimed certificate. The use case for the reference parameter is you can pass your lead identifier, which will provide another reference point 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.
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.
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 a vendor.
If you use our LeadConduit platform, the vendor will be automatically sent with each certificate claim request.
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
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 to claim the certificate 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.
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.
Scanning for Forbidden Text
To search for forbidden text, use the
scan! parameter in the claim call. If TrustedForm's search (also case and whitespace insensitive) finds that text in the HTML document, the message "string found in snapshot" will be returned 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
scan! in a single claim call. If including both you must look for the corresponding messages in the
warnings key of the claim response ("string not found in snapshot" or "string found in snapshot", respectively).
For more information, see page scanning.
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.
- 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 or HTTP 410 Gone will be returned.
- If you have not authenticated correctly using your API key, an HTTP 403 Forbidden will be returned.
- If the certificate id is formatted incorrectly, a 400 Bad Request or 406 Not Acceptable will be returned.
- If you receive a 500, 502 or 503, please retry the claim, if it continues to fail, please contact email@example.com
If you receive any response code other than those above, please let us know.
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.
The following fields are available for every certificate record issued by TrustedForm
- token — Uniquely identifies this certificate
- ip — The consumer's public IP address
- parent_location — If the page was framed, the parent frame's URL
- framed — true or false, depending on whether the form is hosted on a framed page
- browser — A human-friendly version of user_agent
- operating_system — A human-friendly version of the user's operating system
- user_agent — The consumer's browser user-agent
- created_at — The time the consumer loaded the vendor's form in UTC, ISO8601 format
- event_duration — The time in milliseconds the user took to complete the form
- expires_at — The date and time the certificate will no longer be available for further claims
- share_url —A shareable URL that allows customers to send TrustedForm certificates to third parties on an as-needed basis
- geo — A hash of geolocation data based on the IP address
- lat — Latitude
- lon — Longitude
- city — City name
- state — State or Province name
- postal_code — Mailing address postal code
- country_code — Country code
- time_zone — Time zone name per the Olson Database
- claims — An array of claim records for this certificate. (See Claim documentation for information about certificate claiming):
- id — The claim identifier
- age — The age of the claim (The time in seconds since the user's last event on the page, minus the time the claim was made)
- page_id — The unique identifier for the page where the cert was generated
- warnings — An array of string warnings revealing any potential problems with the cert or claim
- reference — The reference provided when the certificate was claimed
- vendor — The vendor name provided when the certificate was claimed
- fingerprints — The lead fingerprints provided when the certificate was claimed
- matching — those that matched a fingerprint collected at the time of consumer signup
- non_matching — those that did not match any fingerprint collected at the time of consumer signup
- share_url - Shareable url to view the claim. See the knowledge base article "How do you share a TrustedForm certificate?"
- created_at — The time the claim was created in UTC, ISO8601 format
- expires_at — The time the will expire your account in UTC, ISO8601 format
- masked — A boolean indicating whether the certificate is masked
- masked_cert_url — A URL with the masked certificate of the claim
- cert — The certificate record for this claim - see the Certificate documentation for additional details on the data available in this field
- scans — A hash of the snapshot scans performed
- found — those that were found on the page snapshot
- not_found — those that were not found on the page snapshot
- warnings — An array of strings indicating possible issues with the certificate. At the moment, only used for Page Scanning.