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": {
    "campaign_id": "summer_promo_2024",
    "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",
      "session_replay_status"
    ],
    "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"
    ]
  }
}
'

import requests

url = "https://cert.trustedform.com/{cert_id}"

payload = {
    "match_lead": { "email": "janedoe@gmail.com" },
    "retain": {
        "campaign_id": "summer_promo_2024",
        "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", "session_replay_status"],
        "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"]
    }
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "Basic <encoded-value>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: 'Basic <encoded-value>'},
  body: JSON.stringify({
    match_lead: {email: 'janedoe@gmail.com'},
    retain: {
      campaign_id: 'summer_promo_2024',
      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',
        'session_replay_status'
      ],
      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']
    }
  })
};

fetch('https://cert.trustedform.com/{cert_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cert.trustedform.com/{cert_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'match_lead' => [
        'email' => 'janedoe@gmail.com'
    ],
    'retain' => [
        'campaign_id' => 'summer_promo_2024',
        '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',
                'session_replay_status'
        ],
        '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cert.trustedform.com/{cert_id}"

	payload := strings.NewReader("{\n  \"match_lead\": {\n    \"email\": \"janedoe@gmail.com\"\n  },\n  \"retain\": {\n    \"campaign_id\": \"summer_promo_2024\",\n    \"reference\": \"1128238382829\",\n    \"vendor\": \"Acme Co.\"\n  },\n  \"insights\": {\n    \"properties\": [\n      \"seconds_on_page\",\n      \"domain\",\n      \"bot_detected\",\n      \"confirmed_owner\",\n      \"ip\",\n      \"approx_ip_geo\",\n      \"browser\",\n      \"age_seconds\",\n      \"created_at\",\n      \"expires_at\",\n      \"form_input_method\",\n      \"form_input_kpm\",\n      \"form_input_wpm\",\n      \"is_framed\",\n      \"is_masked\",\n      \"num_sensitive_content_elements\",\n      \"num_sensitive_form_elements\",\n      \"page_url\",\n      \"parent_page_url\",\n      \"os\",\n      \"session_replay_status\"\n    ],\n    \"scans\": {\n      \"forbidden\": [\n        \"free\",\n        \"ipad\"\n      ],\n      \"required\": [\n        \"home security system\"\n      ]\n    }\n  },\n  \"verify\": {\n    \"advertiser_name\": \"Acme Inc.\",\n    \"min_contrast_ratio_required\": 7,\n    \"min_font_size_px_required\": 16,\n    \"opt_in_types_allowed\": [\n      \"manual\",\n      \"pre-selected\",\n      \"non-interactive\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://cert.trustedform.com/{cert_id}")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "Basic <encoded-value>")
  .body("{\n  \"match_lead\": {\n    \"email\": \"janedoe@gmail.com\"\n  },\n  \"retain\": {\n    \"campaign_id\": \"summer_promo_2024\",\n    \"reference\": \"1128238382829\",\n    \"vendor\": \"Acme Co.\"\n  },\n  \"insights\": {\n    \"properties\": [\n      \"seconds_on_page\",\n      \"domain\",\n      \"bot_detected\",\n      \"confirmed_owner\",\n      \"ip\",\n      \"approx_ip_geo\",\n      \"browser\",\n      \"age_seconds\",\n      \"created_at\",\n      \"expires_at\",\n      \"form_input_method\",\n      \"form_input_kpm\",\n      \"form_input_wpm\",\n      \"is_framed\",\n      \"is_masked\",\n      \"num_sensitive_content_elements\",\n      \"num_sensitive_form_elements\",\n      \"page_url\",\n      \"parent_page_url\",\n      \"os\",\n      \"session_replay_status\"\n    ],\n    \"scans\": {\n      \"forbidden\": [\n        \"free\",\n        \"ipad\"\n      ],\n      \"required\": [\n        \"home security system\"\n      ]\n    }\n  },\n  \"verify\": {\n    \"advertiser_name\": \"Acme Inc.\",\n    \"min_contrast_ratio_required\": 7,\n    \"min_font_size_px_required\": 16,\n    \"opt_in_types_allowed\": [\n      \"manual\",\n      \"pre-selected\",\n      \"non-interactive\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://cert.trustedform.com/{cert_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = 'Basic <encoded-value>'
request.body = "{\n  \"match_lead\": {\n    \"email\": \"janedoe@gmail.com\"\n  },\n  \"retain\": {\n    \"campaign_id\": \"summer_promo_2024\",\n    \"reference\": \"1128238382829\",\n    \"vendor\": \"Acme Co.\"\n  },\n  \"insights\": {\n    \"properties\": [\n      \"seconds_on_page\",\n      \"domain\",\n      \"bot_detected\",\n      \"confirmed_owner\",\n      \"ip\",\n      \"approx_ip_geo\",\n      \"browser\",\n      \"age_seconds\",\n      \"created_at\",\n      \"expires_at\",\n      \"form_input_method\",\n      \"form_input_kpm\",\n      \"form_input_wpm\",\n      \"is_framed\",\n      \"is_masked\",\n      \"num_sensitive_content_elements\",\n      \"num_sensitive_form_elements\",\n      \"page_url\",\n      \"parent_page_url\",\n      \"os\",\n      \"session_replay_status\"\n    ],\n    \"scans\": {\n      \"forbidden\": [\n        \"free\",\n        \"ipad\"\n      ],\n      \"required\": [\n        \"home security system\"\n      ]\n    }\n  },\n  \"verify\": {\n    \"advertiser_name\": \"Acme Inc.\",\n    \"min_contrast_ratio_required\": 7,\n    \"min_font_size_px_required\": 16,\n    \"opt_in_types_allowed\": [\n      \"manual\",\n      \"pre-selected\",\n      \"non-interactive\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "outcome": "success",
  "reason": "null",
  "match_lead": {
    "email": "janedoe@gmail.com",
    "phone": "51125551212",
    "result": {
      "email_match": true,
      "phone_match": true,
      "success": true
    }
  },
  "retain": {
    "campaign_id": "summer_promo_2024",
    "reference": "1128238382829",
    "results": {
      "expires_at": "2023-07-18T12:03:52.000Z",
      "masked_cert_url": "<string>",
      "previously_retained": "false",
      "session_replay_status": "available"
    },
    "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,
      "session_replay_status": "available"
    },
    "scans": {
      "forbidden": [
        "free"
      ],
      "required": [
        "offer"
      ],
      "result": {
        "forbidden": {
          "found": [],
          "not_found": [
            "free"
          ]
        },
        "required": {
          "found": [],
          "not_found": [
            "offer"
          ]
        },
        "success": false
      }
    }
  },
  "verify": {
    "advertiser_name": "Acme Inc.",
    "consent_language_acceptance_enabled": true,
    "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
    }
  }
}

{
  "errors": {
    "detail": "Malformed certificate id"
  },
  "message": "Malformed certificate id",
  "outcome": "error",
  "reason": "Malformed certificate id"
}

{
  "outcome": "error",
  "reason": "Unauthorized"
}

{
  "outcome": "error",
  "reason": "Account is inactive"
}

{
  "outcome": "error",
  "reason": "Unavailable product requested"
}

{
  "outcome": "error",
  "reason": "TrustedForm certificate has expired or could not be found"
}

{
  "outcome": "error",
  "reason": "Certificate is not claimable"
}

{
  "outcome": "error",
  "reason": "Certificate has been claimed too many times"
}

Certificate URL

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.

POST

{cert_id}

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": {
    "campaign_id": "summer_promo_2024",
    "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",
      "session_replay_status"
    ],
    "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"
    ]
  }
}
'

import requests

url = "https://cert.trustedform.com/{cert_id}"

payload = {
    "match_lead": { "email": "janedoe@gmail.com" },
    "retain": {
        "campaign_id": "summer_promo_2024",
        "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", "session_replay_status"],
        "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"]
    }
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "Basic <encoded-value>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: 'Basic <encoded-value>'},
  body: JSON.stringify({
    match_lead: {email: 'janedoe@gmail.com'},
    retain: {
      campaign_id: 'summer_promo_2024',
      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',
        'session_replay_status'
      ],
      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']
    }
  })
};

fetch('https://cert.trustedform.com/{cert_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cert.trustedform.com/{cert_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'match_lead' => [
        'email' => 'janedoe@gmail.com'
    ],
    'retain' => [
        'campaign_id' => 'summer_promo_2024',
        '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',
                'session_replay_status'
        ],
        '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cert.trustedform.com/{cert_id}"

	payload := strings.NewReader("{\n  \"match_lead\": {\n    \"email\": \"janedoe@gmail.com\"\n  },\n  \"retain\": {\n    \"campaign_id\": \"summer_promo_2024\",\n    \"reference\": \"1128238382829\",\n    \"vendor\": \"Acme Co.\"\n  },\n  \"insights\": {\n    \"properties\": [\n      \"seconds_on_page\",\n      \"domain\",\n      \"bot_detected\",\n      \"confirmed_owner\",\n      \"ip\",\n      \"approx_ip_geo\",\n      \"browser\",\n      \"age_seconds\",\n      \"created_at\",\n      \"expires_at\",\n      \"form_input_method\",\n      \"form_input_kpm\",\n      \"form_input_wpm\",\n      \"is_framed\",\n      \"is_masked\",\n      \"num_sensitive_content_elements\",\n      \"num_sensitive_form_elements\",\n      \"page_url\",\n      \"parent_page_url\",\n      \"os\",\n      \"session_replay_status\"\n    ],\n    \"scans\": {\n      \"forbidden\": [\n        \"free\",\n        \"ipad\"\n      ],\n      \"required\": [\n        \"home security system\"\n      ]\n    }\n  },\n  \"verify\": {\n    \"advertiser_name\": \"Acme Inc.\",\n    \"min_contrast_ratio_required\": 7,\n    \"min_font_size_px_required\": 16,\n    \"opt_in_types_allowed\": [\n      \"manual\",\n      \"pre-selected\",\n      \"non-interactive\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://cert.trustedform.com/{cert_id}")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "Basic <encoded-value>")
  .body("{\n  \"match_lead\": {\n    \"email\": \"janedoe@gmail.com\"\n  },\n  \"retain\": {\n    \"campaign_id\": \"summer_promo_2024\",\n    \"reference\": \"1128238382829\",\n    \"vendor\": \"Acme Co.\"\n  },\n  \"insights\": {\n    \"properties\": [\n      \"seconds_on_page\",\n      \"domain\",\n      \"bot_detected\",\n      \"confirmed_owner\",\n      \"ip\",\n      \"approx_ip_geo\",\n      \"browser\",\n      \"age_seconds\",\n      \"created_at\",\n      \"expires_at\",\n      \"form_input_method\",\n      \"form_input_kpm\",\n      \"form_input_wpm\",\n      \"is_framed\",\n      \"is_masked\",\n      \"num_sensitive_content_elements\",\n      \"num_sensitive_form_elements\",\n      \"page_url\",\n      \"parent_page_url\",\n      \"os\",\n      \"session_replay_status\"\n    ],\n    \"scans\": {\n      \"forbidden\": [\n        \"free\",\n        \"ipad\"\n      ],\n      \"required\": [\n        \"home security system\"\n      ]\n    }\n  },\n  \"verify\": {\n    \"advertiser_name\": \"Acme Inc.\",\n    \"min_contrast_ratio_required\": 7,\n    \"min_font_size_px_required\": 16,\n    \"opt_in_types_allowed\": [\n      \"manual\",\n      \"pre-selected\",\n      \"non-interactive\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://cert.trustedform.com/{cert_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = 'Basic <encoded-value>'
request.body = "{\n  \"match_lead\": {\n    \"email\": \"janedoe@gmail.com\"\n  },\n  \"retain\": {\n    \"campaign_id\": \"summer_promo_2024\",\n    \"reference\": \"1128238382829\",\n    \"vendor\": \"Acme Co.\"\n  },\n  \"insights\": {\n    \"properties\": [\n      \"seconds_on_page\",\n      \"domain\",\n      \"bot_detected\",\n      \"confirmed_owner\",\n      \"ip\",\n      \"approx_ip_geo\",\n      \"browser\",\n      \"age_seconds\",\n      \"created_at\",\n      \"expires_at\",\n      \"form_input_method\",\n      \"form_input_kpm\",\n      \"form_input_wpm\",\n      \"is_framed\",\n      \"is_masked\",\n      \"num_sensitive_content_elements\",\n      \"num_sensitive_form_elements\",\n      \"page_url\",\n      \"parent_page_url\",\n      \"os\",\n      \"session_replay_status\"\n    ],\n    \"scans\": {\n      \"forbidden\": [\n        \"free\",\n        \"ipad\"\n      ],\n      \"required\": [\n        \"home security system\"\n      ]\n    }\n  },\n  \"verify\": {\n    \"advertiser_name\": \"Acme Inc.\",\n    \"min_contrast_ratio_required\": 7,\n    \"min_font_size_px_required\": 16,\n    \"opt_in_types_allowed\": [\n      \"manual\",\n      \"pre-selected\",\n      \"non-interactive\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "outcome": "success",
  "reason": "null",
  "match_lead": {
    "email": "janedoe@gmail.com",
    "phone": "51125551212",
    "result": {
      "email_match": true,
      "phone_match": true,
      "success": true
    }
  },
  "retain": {
    "campaign_id": "summer_promo_2024",
    "reference": "1128238382829",
    "results": {
      "expires_at": "2023-07-18T12:03:52.000Z",
      "masked_cert_url": "<string>",
      "previously_retained": "false",
      "session_replay_status": "available"
    },
    "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,
      "session_replay_status": "available"
    },
    "scans": {
      "forbidden": [
        "free"
      ],
      "required": [
        "offer"
      ],
      "result": {
        "forbidden": {
          "found": [],
          "not_found": [
            "free"
          ]
        },
        "required": {
          "found": [],
          "not_found": [
            "offer"
          ]
        },
        "success": false
      }
    }
  },
  "verify": {
    "advertiser_name": "Acme Inc.",
    "consent_language_acceptance_enabled": true,
    "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
    }
  }
}

{
  "errors": {
    "detail": "Malformed certificate id"
  },
  "message": "Malformed certificate id",
  "outcome": "error",
  "reason": "Malformed certificate id"
}

{
  "outcome": "error",
  "reason": "Unauthorized"
}

{
  "outcome": "error",
  "reason": "Account is inactive"
}

{
  "outcome": "error",
  "reason": "Unavailable product requested"
}

{
  "outcome": "error",
  "reason": "TrustedForm certificate has expired or could not be found"
}

{
  "outcome": "error",
  "reason": "Certificate is not claimable"
}

{
  "outcome": "error",
  "reason": "Certificate has been claimed too many times"
}

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

MatchLeadEmailParameters
MatchLeadPhoneParameters
MatchLeadPhoneEmailParameters

Show child attributes

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.

Show child attributes

insights

InsightsParameters · object

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

Show child attributes

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",
    "session_replay_status"
  ],
  "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 consent_language_acceptance_enabled, min_font_size_px_required, min_contrast_ratio_required, and opt_in_types_allowed parameters are optional.

Show child attributes

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

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.

Show child attributes

Example:

{
  "email": "janedoe@gmail.com",
  "phone": "51125551212",
  "result": {
    "email_match": true,
    "phone_match": true,
    "success": true
  }
}

retain

RetainResult · object

Show child attributes

insights

InsightsResult · object

The Insights data points and page scan results for a certificate.

Not every data point is reported by every certificate type. A data point that a certificate's type does not support is returned as null when requested.

Property	Web	Mobile	Facebook Lead Ads	Social
`age_seconds`	✓	✓	✓	✓
`approx_ip_geo`	✓	✓	—	✓
`bot_detected`	✓	—	—	—
`browser`	✓	—	—	—
`confirmed_owner`	✓	✓	✓	✓
`created_at`	✓	✓	✓	✓
`domain`	✓	—	—	✓
`expires_at`	✓	✓	✓	✓
`form_input_kpm`	✓	—	—	—
`form_input_method`	✓	—	—	—
`form_input_wpm`	✓	—	—	—
`ip`	✓	✓	—	✓
`is_framed`	✓	—	—	—
`is_masked`	✓	✓	—	—
`num_sensitive_content_elements`	✓	—	—	—
`num_sensitive_form_elements`	✓	—	—	—
`os`	✓	✓	—	✓
`page_url`	✓	—	—	—
`parent_page_url`	✓	—	—	—
`seconds_on_page`	✓	✓	✓	✓
`session_replay_status`	✓	✓	✓	✓

Show child attributes

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,
    "session_replay_status": "available"
  },
  "scans": {
    "forbidden": ["free"],
    "required": ["offer"],
    "result": {
      "forbidden": { "found": [], "not_found": ["free"] },
      "required": { "found": [], "not_found": ["offer"] },
      "success": false
    }
  }
}

verify

VerifyResult · object

Show child attributes

Example:

{
  "advertiser_name": "Acme Inc.",
  "consent_language_acceptance_enabled": true,
  "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
  }
}