Search

Certificate API Version 4.0

Ayesha Akhtar
Ayesha Akhtar
  • Updated

Feature Snapshot

Summary:
Certificate API Version 4.0 is TrustedForm’s latest API interface that introduced the concept of specifying the product offerings you want to use to provide a clearer schema, enhanced security, and giving you more control over how your business uses TrustedForm.

Key Benefits:

  • Separates operations by mandating distinct actions, which improves data clarity and troubleshooting.
  • Enforces mandatory lead matching of submitted lead data (email/phone) when retaining certifciates to protect you against risks to your data integrity.
  • Offers an enhanced, well-structured JSON response that simplifies integration and error handling, facilitating smooth migration from older API versions.

Typical Use Cases:

  • Automating the long term storage of TrustedForm certificates to document consumer consent for legal and audit purposes with TrustedForm Retain.
  • Appending lead metadata from TrustedForm Insights to optimize lead management.
  • Confirm that TrustedForm certificates include documented evidence of meaningful consent through compliance checks with TrustedForm Verify.

How the Certificate API Version 4.0 works

Certificate API Version 4.0 requires that every API request includes the HTTP header “api-version: 4.0”. In this version, operations are clearly separated: the “retain” object stores a certificate in your TrustedForm account for long-term legal protection, while the “match_lead” object accepts submitted lead data to perform mandatory fingerprint matching. This new design returns a structured JSON response that categorizes outcomes into “success”, “failure”, or “error” for each operation, enabling developers to implement clear logic and robust error handling.

Step‑by‑Step Instructions

  1. Include the API Version Header:
    Add the HTTP header api-version: 4.0 to every API request to ensure that the new schema is used.
  2. Construct the Request Payload:
    Create a JSON payload that contains separate objects as shown in our API Documentation.
  3. Update Your Integration Logic:
    Modify your response parser to extract key fields such as outcome.
  4. Test the Endpoint:
    Execute a test API call via cURL or Postman to verify that a valid JSON response is returned and that operations are processed correctly.

Expected Result:
A successful API call will return an HTTP 200 response with a JSON payload containing the results of the operations run.

Best Practices

  • Migrate Early:
    Transition from API versions 2.0 or 3.0 to Version 4.0 as soon as possible to ensure uninterrupted service before older versions are sunset.
  • Thorough Testing:
    Validate your integration to confirm that your payload and response parsing logic are fully compatible with the new schema.
  • Robust Logging:
    Log every API request and response to enable quick diagnosis and troubleshooting in case of errors.
  • Domain Verification:
    Ensure that all your lead-generating domains are register with ActiveProspect.
  • Error Handling:
    Implement separate routines for handling “failure” outcomes (e.g. where the certificate is stored but data mismatches occur) versus “error” outcomes (where the API request fails due to formatting or authentication issues).

Troubleshooting

Symptom / Error Likely Cause Resolution
HTTP 400 / 406 Malformed certificate ID or invalid JSON payload structure Validate that the certificate URL is correctly formatted and that the JSON payload strictly adheres to the API schema.
HTTP 402 Account subscription or payment issues preventing v4.0 access Check your account settings and confirm that your subscription includes access to API Version 4.0; contact support if needed.
HTTP 403 Incorrect API key authentication Verify that the correct API key is included using HTTP Basic Authentication with “API” as the username.
HTTP 404 Certificate not found, expired, or outside the allowable retention window Ensure that the certificate URL is correct and that the retention request is made within the valid timeframe (e.g., 72 hours or extended to 90 days for submitted leads).
HTTP 500 / 502 / 503 Server-side or network errors Retry the API request after a short delay; if the issue persists, consult TrustedForm support with detailed logs.
Timeout Errors Network latency or insufficient client timeout settings Increase the client timeout settings and retry the request.

Frequently Asked Questions (FAQ)

Q: What is Certificate API Version 4.0?
A: It is the latest version of TrustedForm’s API, designed to document and permanently store consumer consent through certificate retention while performing mandatory lead matching via fingerprinting.

Q: Why is Certificate API Version 4.0 important?
A: It significantly improves usability by separating usage of different products, providing a clearer, more maintainable API schema that simplifies usage.

Q: How do I use Certificate API Version 4.0?
A: Update your integration to include the HTTP header api-version: 4.0, structure your JSON request, and adjust your response parsing logic as specified in our API Documentation.

Q: How do I switch from version 2.0/3.0 to 4.0?
A: For self‑service customers, simply follow the instructions above to begin using API Version 4.0. Managed customers should consult their Client Success Manager for migration support.

Q: What are the key differences between version 2.0/3.0 and 4.0?
A: Unlike version 2.0/3.0 where multiple products were bundled together, version 4.0 separates these functions, requires mandatory LEAD matching, and offers a revamped, more readable schema that enhances error reporting and integration flexibility. Full details can be found in these documents: API Version 3.0 vs 4.0 & API Version 2.0 vs 4.0

Glossary

Term Definition
Retain The operation used to permanently store a TrustedForm certificate in your account for future verification and legal protection.
Match Lead The operation that performs fingerprint matching, comparing submitted lead data (email/phone) with the data captured in the certificate.
Certificate API V4.0 The latest version of the TrustedForm Certificate API featuring separated operations for certificate retention and lead matching.
Outcome A property in the API response that indicates the result of an operation, typically “success”, “failure”, or “error”.
API Version Header An HTTP header (api-version: 4.0) that specifies the version of the API to be used for processing a request.

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.