When a TrustedForm certificate is received with a lead, you should make a claim on the certificate. Making a claim imparts the following benefits:
- Certificate authenticity is verified
- Certificate details can be extracted for storage in your system
- Certificate details including the snapshot and page image are stored in your account for later reference
- Certificate lead fingerprints can be checked using the lead data you received
- Tracking information such as the vendor and a reference code can be provided to TrustedForm for later reference
In addition to providing the cert data, the following fields are available on a claim:
- 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
- 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.
Creating a claim
When a claim is made against a cert, a new claim record is stored in TrustedForm.
Retrieving a claim
After you have created a claim, you can retrieve it using an HTTP GET call. Specify the Accept header in order to get JSON.
NOTE: This query will only give you claims for the last three days
NOTE: This query will only give you claims for the last three days.
Claims are listed in chronological order. The following parameters can be used to filter the list.
- limit — max number of claims to return (must be less than 100)
- before_id — return claims older than that referenced by this ID
- page_id — return claims only for this page
- desc=true — return claims in reverse chronological order
Claims cannot be updated.
Claims are automatically deleted by TrustedForm based on the retention threshold setting on your account. Claims cannot be individually deleted.
You can change the claim retention threshold by logging into the TrustedForm application with your browser, or, by using the Account API to change the claim_dtl as shown below.
Setting a reliable timeout for pulling snapshots
Most users who pull the snapshot via the API immediately after claiming the TrustedForm certificate won't need to set a timeout to pull the snapshot successfully. However, if you are experiencing a 404 status code when trying to pull the snapshot immediately after claiming the certificate - setting a 1 minute timeout before making another request to the API for the recently claimed certificate will allow for a successful request and avoid the 404 status code.