Verification API

The Verification API lets you confirm that a consumer gave consent, look up certificate details, retain session data for compliance, and process opt-out revocations. Every verification check costs $0.015 and is billed from your prepaid wallet on a pay-as-you-go basis.

Base URL

https://api.econsent.org

Authentication

All endpoints (except Opt-Out) require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

The Opt-Out endpoint is unauthenticated but rate-limited to 10 requests per minute per IP address.

---

POST /verify/match: Exact Match

Check whether specific consent text exactly matches what was recorded in a certificate. Use this when you need to prove that a consumer agreed to a particular disclosure word-for-word, for example during a TCPA compliance audit.

Request body

Parameter	Type	Required	Description
certificate_id	string	Yes	The certificate ID to verify
company_id	string	Yes	Your company ID
consent	string	Yes	The exact consent text to match against the certificate
originator_company_id	string	No	The company that originally captured consent (for third-party verification)

Response

Field	Type	Description
valid	boolean	Whether the consent text matched a record in the certificate
consent_opt_in	string	ISO 8601 timestamp of when consent was given
origin	string	The source where consent was captured (e.g., form URL)
consent_types	array	List of consent type labels found in the certificate
verification_type	string	first_party if you captured the consent, third_party if another company did

Example

curl

curl -X POST https://api.econsent.org/verify/match \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_id": "EC-abc123-def456",
    "company_id": "comp-abc",
    "consent": "I agree to receive marketing calls and text messages from Example Corp."
  }'

Node.js

const API_TOKEN = process.env.ECONSENT_API_TOKEN;

async function verifyExactMatch(certificateId, companyId, consentText) {
  const response = await fetch('https://api.econsent.org/verify/match', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      certificate_id: certificateId,
      company_id: companyId,
      consent: consentText,
    }),
  });

  const data = await response.json();

  if (data.valid) {
    console.log('Consent verified at:', data.consent_opt_in);
    console.log('Consent types:', data.consent_types);
    console.log('Verification type:', data.verification_type);
  } else {
    console.log('Consent text did not match the certificate');
  }

  return data;
}

// Usage
verifyExactMatch(
  'EC-abc123-def456',
  'comp-abc',
  'I agree to receive marketing calls and text messages from Example Corp.'
);

Success response (200)

{
  "valid": true,
  "consent_opt_in": "2026-03-18T10:30:00Z",
  "origin": "https://example.com/signup",
  "consent_types": ["tcpa-express-consent"],
  "verification_type": "first_party"
}

Tip

Each verification call charges $0.015 from your wallet. Failed matches still count as a verification check.

---

POST /verify/partial-match: Partial Match

Search for a keyword or phrase within the recorded consent text. This is useful when you need to check whether a certificate contains a particular term (like a company name or product) but do not have the full consent wording.

Request body

Parameter	Type	Required	Description
certificate_id	string	Yes	The certificate ID to verify
company_id	string	Yes	Your company ID
term	string	Yes	The search term or phrase to look for within the consent text
originator_company_id	string	No	The company that originally captured consent (for third-party verification)

Response

Field	Type	Description
valid	boolean	Whether the term was found in the certificate’s consent text
consent_opt_in	string	ISO 8601 timestamp of when consent was given
origin	string	The source where consent was captured
verification_type	string	first_party or third_party

Example

curl

curl -X POST https://api.econsent.org/verify/partial-match \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_id": "EC-abc123-def456",
    "company_id": "comp-abc",
    "term": "marketing calls"
  }'

Node.js

async function verifyPartialMatch(certificateId, companyId, searchTerm) {
  const response = await fetch('https://api.econsent.org/verify/partial-match', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      certificate_id: certificateId,
      company_id: companyId,
      term: searchTerm,
    }),
  });

  return response.json();
}

// Check if the certificate mentions "marketing calls"
const result = await verifyPartialMatch('EC-abc123-def456', 'comp-abc', 'marketing calls');
console.log('Match found:', result.valid);

Success response (200)

{
  "valid": true,
  "consent_opt_in": "2026-03-18T10:30:00Z",
  "origin": "https://example.com/signup",
  "verification_type": "first_party"
}

Tip

Use exact match when you need to verify specific consent language for legal compliance. Use partial match when you want to check for a keyword or company name without needing the full text.

---

POST /verify/certificate-info: Certificate Info

Retrieve metadata about a certificate without performing a consent text match. Use this to check whether a certificate exists, when it was created, and how many consent records it contains.

Request body

Parameter	Type	Required	Description
certificate_id	string	Yes	The certificate ID to look up
company_id	string	Yes	Your company ID
property_id	string	Yes	Your property ID

Example

curl

curl -X POST https://api.econsent.org/verify/certificate-info \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_id": "EC-abc123-def456",
    "company_id": "comp-abc",
    "property_id": "prop-xyz"
  }'

Node.js

async function getCertificateInfo(certificateId, companyId, propertyId) {
  const response = await fetch('https://api.econsent.org/verify/certificate-info', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      certificate_id: certificateId,
      company_id: companyId,
      property_id: propertyId,
    }),
  });

  const data = await response.json();

  if (data.valid) {
    console.log('Certificate created:', data.created_timestamp);
    console.log('Consent records:', data.consent_count);
    console.log('Has consents:', data.has_consents);
  }

  return data;
}

const info = await getCertificateInfo('EC-abc123-def456', 'comp-abc', 'prop-xyz');

Success response (200)

{
  "valid": true,
  "certificate_id": "EC-abc123-def456",
  "created_timestamp": "2026-03-18T10:30:00Z",
  "has_consents": true,
  "consent_count": 3,
  "events_combined": {}
}

Response fields

Field	Type	Description
valid	boolean	Whether the certificate was found
certificate_id	string	The certificate ID
created_timestamp	string	ISO 8601 timestamp of when the certificate was created
has_consents	boolean	Whether the certificate contains any consent records
consent_count	number	Number of consent records in the certificate
events_combined	object	Combined event data from the session

---

POST /verify/session/:company_id: Retain Session

Mark a session for long-term retention. By default, raw session recordings are stored for a limited period. Call this endpoint to keep a session’s recording data available beyond the default retention window. This is useful when you know a session may be needed for future litigation or audits.

A session retention fee is charged from your wallet.

URL parameters

Parameter	Type	Required	Description
company_id	string	Yes	Your company ID (in the URL path)

Request body

Parameter	Type	Required	Description
session_id	string	Yes	The session ID to retain

Example

curl

curl -X POST https://api.econsent.org/verify/session/comp-abc \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-12345"
  }'

Node.js

async function retainSession(companyId, sessionId) {
  const response = await fetch(
    `https://api.econsent.org/verify/session/${companyId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ session_id: sessionId }),
    }
  );

  return response.json();
}

// Retain a session for long-term storage
await retainSession('comp-abc', 'sess-12345');

---

POST /verify/certificate/:company_id: Retain Certificate

Mark a certificate for long-term retention. Similar to session retention, this ensures the certificate and its associated data remain accessible beyond the default retention period.

A certificate retention fee is charged from your wallet.

URL parameters

Parameter	Type	Required	Description
company_id	string	Yes	Your company ID (in the URL path)

Request body

Parameter	Type	Required	Description
session_id	string	Yes	The session ID associated with the certificate to retain

Example

curl

curl -X POST https://api.econsent.org/verify/certificate/comp-abc \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-12345"
  }'

Node.js

async function retainCertificate(companyId, sessionId) {
  const response = await fetch(
    `https://api.econsent.org/verify/certificate/${companyId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ session_id: sessionId }),
    }
  );

  return response.json();
}

// Retain a certificate for long-term storage
await retainCertificate('comp-abc', 'sess-12345');

---

POST /opt-out: Revocation

Allow consumers to revoke their consent. This endpoint is unauthenticated so it can be called from consumer-facing opt-out pages, but it is rate-limited to 10 requests per minute per IP to prevent abuse.

You must provide at least one identifier (certificate_id, email, or mobile) so the system knows which consent records to revoke.

Request body

Parameter	Type	Required	Description
company_id	string	Yes	The company ID the consent was given to
certificate_id	string	No	Revoke a specific certificate
email	string	No	Revoke all certificates matching this email
mobile	string	No	Revoke all certificates matching this phone number
reason	string	No	Optional reason for the revocation

Caution

At least one of certificate_id, email, or mobile must be provided. Requests with no identifier will return a 400 error.

Example

curl

curl -X POST https://api.econsent.org/opt-out \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "comp-abc",
    "email": "consumer@example.com",
    "reason": "No longer interested"
  }'

Node.js

async function revokeConsent(companyId, { certificateId, email, mobile, reason }) {
  const body = { company_id: companyId };

  if (certificateId) body.certificate_id = certificateId;
  if (email) body.email = email;
  if (mobile) body.mobile = mobile;
  if (reason) body.reason = reason;

  const response = await fetch('https://api.econsent.org/opt-out', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  const data = await response.json();

  if (data.success) {
    console.log(`Revoked ${data.revoked} certificate(s):`, data.certificates);
  }

  return data;
}

// Revoke by email
await revokeConsent('comp-abc', {
  email: 'consumer@example.com',
  reason: 'No longer interested',
});

// Revoke a specific certificate
await revokeConsent('comp-abc', {
  certificateId: 'EC-abc123-def456',
});

Success response (200)

{
  "success": true,
  "revoked": 2,
  "certificates": ["EC-abc123-def456", "EC-ghi789-jkl012"],
  "timestamp": "2026-03-18T10:35:00Z"
}

Response fields

Field	Type	Description
success	boolean	Whether the revocation was processed
revoked	number	Number of certificates that were revoked
certificates	array	List of certificate IDs that were revoked
timestamp	string	ISO 8601 timestamp of when the revocation was processed

Note

Once a certificate is revoked, all verification endpoints will return a 403 error for that certificate with the message “This session has opted out.”

---

Third-party verification

To verify a certificate that was captured by a different company, include the originator_company_id field in your exact match or partial match request. This tells the API that you are verifying consent that was originally collected by another organization.

{
  "certificate_id": "EC-abc123-def456",
  "company_id": "your-company-id",
  "consent": "I agree to marketing emails",
  "originator_company_id": "originating-company-id"
}

Requirements

For third-party verification to succeed, the originating company must:

1. Enable third_party_verification_enabled on their account.
2. Add the verifying company’s ID to their authorized_third_parties list.

If either condition is not met, the API returns 403 Forbidden.

---

Revocation checking

The Verification API automatically checks whether a certificate has been revoked before returning results. If the consumer has opted out, the verification endpoints return:

{
  "status": 403,
  "error": "This session has opted out"
}

---

Error responses

Status	Meaning	Example
400	Bad request: missing or malformed required fields	Missing certificate_id
401	Unauthorized: invalid or missing Bearer token	Expired API token
403	Forbidden: certificate opted out, or unauthorized third-party	Consumer revoked consent
404	Not found: certificate does not exist	Invalid certificate_id
429	Rate limited: too many requests	Exceeded 10/min on opt-out endpoint

---

Pricing

Action	Cost
Verification check (exact match, partial match)	$0.015 per check
Session retention	Charged from wallet
Certificate retention	Charged from wallet
Opt-out revocation	Free

All verification costs are deducted from your prepaid wallet balance. You can top up your wallet from the dashboard.

---

Next steps

• Authentication. Authentication methods and API tokens
• Revocation & Opt-Out. Consumer consent revocation details
• Consent Certificates. Certificate format and generation details