Skip to main content
POST
/
{cert_id}
Run Certificate Operations
curl --request POST \
  --url https://cert.trustedform.com/{cert_id} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "match_lead": {
    "email": "janedoe@gmail.com"
  },
  "retain": {
    "reference": "1128238382829",
    "vendor": "Acme Co."
  },
  "insights": {
    "properties": [
      "seconds_on_page",
      "domain",
      "bot_detected",
      "confirmed_owner",
      "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.",
    "min_contrast_ratio_required": 7,
    "min_font_size_px_required": 16,
    "opt_in_types_allowed": [
      "manual",
      "pre-selected",
      "non-interactive"
    ]
  }
}
'
{
  "outcome": "success",
  "reason": "null",
  "match_lead": {
    "email": "janedoe@gmail.com",
    "phone": "51125551212",
    "result": {
      "email_match": true,
      "phone_match": true,
      "success": true
    }
  },
  "retain": {
    "reference": "1128238382829",
    "results": {
      "expires_at": "2023-07-18T12:03:52.000Z",
      "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"
        }
      },
      "confirmed_owner": "ActiveProspect, Inc.",
      "created_at": "2024-09-18T17:07:09.000Z",
      "domain": "example.com",
      "expires_at": "2024-12-20T17:07:09.000Z",
      "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"
      }
    ],
    "min_contrast_ratio_required": 7,
    "min_font_size_px_required": 16,
    "opt_in_types_allowed": [
      "manual",
      "pre-selected",
      "non-interactive"
    ],
    "result": {
      "form_submitted": true,
      "language_approved": true,
      "min_contrast_ratio_satisfied": true,
      "min_font_size_px_satisfied": true,
      "one_to_one": true,
      "opt_in_types_satisfied": true,
      "success": true
    }
  }
}

Authorizations

​
Authorization
string
header
required

TrustedForm uses HTTP Basic Authentication with the username API and your API key as the password.

For example: API:1f1b96c9150d8050e858c043d543bb4eadae0e6f'

Headers

​
Content-Type
string
required

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.

Example:

"4.0"

Path Parameters

​
cert_id
string
required

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

Maximum string length: 255

Body

application/json
​
match_lead
MatchLeadEmailParameters · object

Match certificate to the lead based on the lead email address

Example:
{ "email": "janedoe@gmail.com" }
​
retain
RetainParameters · object

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.

​
insights
InsightsParameters · object

Request individual Insights data points (properties) to be returned and terms for which to scan for in a certificate session replay.

Example:
{
  "properties": [
    "seconds_on_page",
    "domain",
    "bot_detected",
    "confirmed_owner",
    "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
VerifyParameters · object

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.

The min_font_size_px_required, min_contrast_ratio_required, and opt_in_types_allowed parameters are optional.

Example:
{
  "advertiser_name": "Acme Inc.",
  "min_contrast_ratio_required": 7,
  "min_font_size_px_required": 16,
  "opt_in_types_allowed": ["manual", "pre-selected", "non-interactive"]
}

Response

OK

​
outcome
enum<string>

The overall outcome of executed operations. Indicates whether the call succeeded, failed, or resulted in an error. Best practice is to use this property to determine if you should purchase a lead. A failure or error indicate that the lead should not be contacted. The reason for failure or error is revealed in the reason property.

Available options:
success,
failure,
error
Example:

"success"

​
reason
string | null

Explanation for a failure or error, otherwise null

Example:

null

​
match_lead
MatchLeadResult · object

The result of the match_lead operation. The email and phone parameters are echoed and the result property reports the outcome of the operation. More information is available in our KB.

If the operation result is not a success, TrustedForm was unable to confirm that the consumer information collected on the cert matches the lead it came with. This is a strong signal that the lead should not be contacted.

The result of the match_lead operation does not impact the behavior of the retain operation.

Example:
{
  "email": "janedoe@gmail.com",
  "phone": "51125551212",
  "result": {
    "email_match": true,
    "phone_match": true,
    "success": true
  }
}
​
retain
RetainResult · object
​
insights
WebInsightsResult · object
Example:
{
  "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"
      }
    },
    "confirmed_owner": "ActiveProspect, Inc.",
    "created_at": "2024-09-18T17:07:09.000Z",
    "domain": "example.com",
    "expires_at": "2024-12-20T17:07:09.000Z",
    "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
VerifyResult · object
Example:
{
  "advertiser_name": "Acme Inc.",
  "languages": [
    {
      "text": "By clicking on the 'Get Rates' button below, I consent to be contacted"
    }
  ],
  "min_contrast_ratio_required": 7,
  "min_font_size_px_required": 16,
  "opt_in_types_allowed": ["manual", "pre-selected", "non-interactive"],
  "result": {
    "form_submitted": true,
    "language_approved": true,
    "min_contrast_ratio_satisfied": true,
    "min_font_size_px_satisfied": true,
    "one_to_one": true,
    "opt_in_types_satisfied": true,
    "success": true
  }
}