Retain API Operation

Feature Snapshot

Summary:
The Retain API Operation is a TrustedForm feature that securely stores a certificate in your account, providing verifiable, long‑term evidence of how a lead was generated.

Key Benefits:

• Offers reliable evidence to help evaluate compliance with telemarketing and advertising regulations
• Supports compliance audits by retaining detailed records of lead events
• Enables real‑time integrations with external system to automate record keeping processes

Typical Use Cases:

• Retaining certificates for legal defense and audit documentation
• Automating certificate storage during lead generation flows
• Rejecting leads when a TrustedForm certificate can not be retained

How the Retain API Operation works

When a TrustedForm certificate is generated during a consumer’s session, the Retain API Operation stores that certificate in your account for future retrieval after receiving a request in accordance with the API Documentation. The operation returns a JSON response that confirms whether the certificate was successfully retained for compliance and audit purposes.

Step‑by‑Step Instructions

1. Configure your API Request:
   • Add the header api-version: 4.0 to signal the use of the latest API schema.
   • Use HTTP Basic Authentication with “API” as the username and your API key as the password.
   • Confirm that your TrustedForm account is enabled for certificate retention.

2. Prepare the JSON Payload:
   • Include an object named "retain" (even if empty) to initiate storage of the certificate.
   • Also include the "match_lead" object with an "email" and/or "phone" operation, which will perform lead matching against the certificate.

3. Send the HTTP POST Request:
   • Post your request to the TrustedForm Certificate URL (formatted as https://cert.trustedform.com/<cert_token>).
   • Ensure the request includes Content-Type: application/json and Accept: application/json headers.

4. Process the Response:
   • On success, the API returns an HTTP 200 status code with a JSON object containing certificate details and an “outcome” field set to “success”.
   • If errors occur, review the JSON error details to troubleshoot the issue.

Expected Result:
The certificate is successfully retained in your TrustedForm account. The API response includes all pertinent certificate details, an outcome field indicating “success”, and any matching data if lead matching is enabled.

Validation & Monitoring (optional)

• Test the Setup:
  Make a sample API call using a valid TrustedForm certificate URL and verify that you receive an HTTP 200 response with the expected JSON payload containing certificate details.

• Where to Monitor?:
  Monitor your TrustedForm Retained Certificates and check API logs to track the outcome and review any error codes for further troubleshooting.

Best Practices

• Always verify the certificate URL begins with https://cert.trustedform.com/ to maintain secure communications.
• Include both the "retain" and "match_lead" objects when you want to automatically verify lead data.
• Store the complete certificate URL with your lead data in your CRM for future audit reference.
• Log every API response (successes and errors) to identify and resolve integration issues promptly.
• Regularly review the TrustedForm API Documentation to ensure your integration adheres to current API specifications and error code updates.

Troubleshooting

Frequently Asked Questions (FAQ)

Q: What is the Retain API Operation?
A: It is the TrustedForm Certificate API operation used to store a TrustedForm certificate in your account, providing independent record of lead generation for compliance and audit purposes.

Q: Why is the Retain API Operation important?
A: Retaining certificates enables you to securely document how and lead was generated and if consent was given to support regulatory compliance with legal standards like the TCPA.

Q: How do I use the Retain API Operation?
A: To use it, include the api-version: 4.0 header in your HTTP request, authenticate using your API key, and send a JSON payload with the "retain" and "match_lead" objects to a TrustedForm Certificate URL via an HTTP POST request.

Q: How fast is the Retain API Operation?
A: Under normal conditions, the API typically responds within 1 to 2 seconds, providing near real‑time feedback on the retention process.

Glossary