Certificate URL

Each Certificate URL acts as the endpoint to a simple RPC API. The HTTP methods listed in this section are used to interact with an individual certificate. Certificate URLs follow a common format, though the format of a certificate ID depends on how the certificate was issued.

https://cert.trustedform.com/eb9fc4dd9bed9ad451a5648946cf4bf09b5bb947

Run Certificate Operations

The TrustedForm Certificate API is able to perform multiple operations based on the parameters sent in the request. Each operation is demonstrated in the request body documentation. The overall outcome of the operations is revealed by the outcome property. Best practice is to base your purchase decision on this property.

Separate documentation about the parameters and results of each operation is available in the Operations reference. and can be used alone or in tandem with another operation. The match_lead operation is required when running the retain operation.

Introduction of TrustedForm Certificate API v4.0
SecurityBasic
Request
path Parameters
cert_id
required
string <= 255 characters

The certificate ID format varies depending on the type of certificate. Certificate ID length will not exceed 255 characters.

Example: eb9fc4dd9bed9ad451a5648946cf4bf09b5bb947
header Parameters
Content-Type
required
string

application/json

Api-Version
string
If your account is configured to use an earlier api-version,
optionally include this header to override the

default behavior and force usage of v4.0. Defaults to your currently
configured API version, visible in
[your settings](https://app.trustedform.com/settings).
Example: 4.0
Request Body schema: application/json
optional
MatchLeadEmailParameters (object) or MatchLeadPhoneParameters (object) or MatchLeadPhoneEmailParameters (object) (MatchLeadParameters)
object (RetainParameters) 
Though both `retain` parameters are optional, we strongly recommend
using them. Doing so will record additional

metadata on your stored certificate which is often of use down the road.
object (InsightsParameters) 
Request individual Insights data points (`properties`) to be returned
and terms for which to scan for in a certificate session replay.
object (VerifyParameters)

The advertiser_name parameter is optional but is required to populate the one_to_one property.

The advertiser_name parameter only applies to the One to One Consent value (returned as one_to_one). It has no effect on any other values returned by the Verify call.

Responses
200

OK

400

Bad Request

401

Incorrect API key

402

Account is inactive or out of funds

403

Uavailable operation requested

404

TrustedForm certificate has expired or could not be found

405

Attempted to claim a 'sandboxed' certificate

422

Unprocessable Entity

post/{cert_id}
Request samples
application/json
{
  • "match_lead": {
    • "email": "janedoe@gmail.com"
    },
  • "retain": {
    • "reference": "1128238382829",
    • "vendor": "Acme Co."
    },
  • "insights": {
    • "properties": [
      • "seconds_on_page",
      • "domain",
      • "bot_detected",
      • "ip",
      • "approx_ip_geo",
      • "browser",
      • "age_seconds",
      • "created_at",
      • "expires_at",
      • "form_input_method",
      • "form_input_kpm",
      • "form_input_wpm",
      • "is_framed",
      • "is_masked",
      • "num_sensitive_content_elements",
      • "num_sensitive_form_elements",
      • "page_url",
      • "parent_page_url",
      • "os"
      ],
    • "scans": {
      • "forbidden": [
        • "free",
        • "ipad"
        ],
      • "required": [
        • "home security system"
        ]
      }
    },
  • "verify": {
    • "advertiser_name": "Acme Inc."
    }
}
Response samples
application/json
{
  • "outcome": "success",
  • "reason": "null",
  • "match_lead": {
    • "email": "janedoe@gmail.com",
    • "phone": "51125551212",
    • "result": {
      • "email_match": true,
      • "phone_match": true,
      • "success": true
      }
    },
  • "retain": {
    • "reference": "1128238382829",
    • "result": {
      • "expires_at": "2023-07-18T12:03:52Z",
      • "masked_cert_url": "string",
      • "previously_retained": "false"
      },
    • "vendor": "Acme Co."
    },
  • "insights": {
    • "properties": {
      • "age_seconds": 76287,
      • "approx_ip_geo": {
        • "city": "Dallas",
        • "country_code": "US",
        • "lat": 32.7451,
        • "lon": -96.8038,
        • "postal_code": "75203",
        • "state": "Texas",
        • "time_zone": "America/Chicago"
        },
      • "bot_detected": false,
      • "browser": {
        • "full": "Chrome 128.0.0.0",
        • "name": "Chrome",
        • "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36",
        • "version": {
          • "full": "128.0.0.0",
          • "major": "128",
          • "minor": "0",
          • "patch": "0"
          }
        },
      • "created_at": "2024-09-18T17:07:09Z",
      • "domain": "example.com",
      • "expires_at": "2024-12-20T17:07:09Z",
      • "form_input_kpm": 234.92560689115115,
      • "form_input_method": [
        • "typing"
        ],
      • "form_input_wpm": 47.355958958168905,
      • "ip": "192.168.0.1",
      • "is_framed": false,
      • "is_masked": false,
      • "num_sensitive_content_elements": 0,
      • "num_sensitive_form_elements": 0,
      • "os": {
        • "full": "Mac OS X 10.15.7",
        • "is_mobile": false,
        • "name": "Mac OS X",
        • "version": {
          • "full": "10.15.7",
          • "major": "10",
          • "minor": "15",
          • "patch": "7"
          }
        },
      • "page_url": "https://www.example.com/contact.html",
      • "parent_page_url": null,
      • "seconds_on_page": 1129
      },
    • "scans": {
      • "forbidden": [
        • "free"
        ],
      • "required": [
        • "offer"
        ],
      • "result": {
        • "forbidden": {
          • "found": [ ],
          • "not_found": [
            • "free"
            ]
          },
        • "required": {
          • "found": [ ],
          • "not_found": [
            • "offer"
            ]
          },
        • "success": false
        }
      }
    },
  • "verify": {
    • "advertiser_name": "Acme Inc.",
    • "languages": [
      • {
        • "text": "By clicking on the 'Get Rates' button below, I consent to be contacted"
        }
      ],
    • "result": {
      • "language_approved": true,
      • "one_to_one": true,
      • "success": true
      }
    }
}