Authentication

All eConsent API requests require authentication. The method you use depends on the type of integration.

Authentication methods

Company ID + Property ID (Standard)

For most API calls, including verification, retention, and opt-out, you authenticate by including your company_id and property_id in the request body.

{
  "company_id": "comp-abc123",
  "property_id": "prop-xyz789",
  "certificate_id": "EC-session123-base64hash"
}

Your Company ID and Property ID are available in the eConsent dashboard at app.econsent.org under Settings and Properties, respectively.

Caution

Treat your Company ID and Property ID as sensitive credentials. Do not expose them in client-side code. All verification calls should be made from your server.

Bearer token (Integrations)

For third-party integrations and webhook-based workflows (such as Meta Lead Ads), authentication uses a Bearer token in the Authorization header:

curl -X POST https://api.econsent.org/api/verify/match \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_id": "EC-session123-base64hash",
    "consent": "I agree to receive calls"
  }'

Bearer tokens are generated in the dashboard under Settings > Integrations. Each token is scoped to a specific company and can be revoked at any time.

Third-party verification

When verifying certificates issued by another company, you must include the originator_company_id field in your request:

{
  "certificate_id": "EC-session123-base64hash",
  "company_id": "your-company-id",
  "property_id": "your-property-id",
  "consent": "I agree to marketing emails",
  "originator_company_id": "originating-company-id"
}

For this to work, the originating company must:

1. Enable the third_party_verification_enabled flag on their account.
2. Add your company to their authorized_third_parties list.

If either condition is not met, the API returns a 403 Unauthorized response.

Getting your credentials

Company ID

1. Log in to app.econsent.org.
2. Navigate to Settings.
3. Your Company ID is displayed on the settings page.

Property ID

1. Navigate to Properties in your dashboard.
2. Select the property you want to use.
3. The Property ID is displayed on the property detail page.

Integration tokens

1. Navigate to Settings > Integrations in your dashboard.
2. Enable the integration you need (Debt Lookup, Email Validation, Phone Validation, or Meta Lead Ads).
3. Copy the generated API token.

Error responses

All authentication failures return standard HTTP error codes:

Status code	Meaning
400	Bad request: missing or malformed required fields
401	Unauthorized: invalid credentials or token
403	Forbidden: certificate opted out, or third-party access not authorized
404	Not found: certificate or property does not exist
429	Rate limited: too many requests

Security best practices

• Server-side only. Never call the eConsent API from client-side JavaScript. Your Company ID and Property ID should remain on your backend.
• Environment variables. Store credentials in environment variables or a secrets manager, not in source code.
• Rotate tokens. Periodically rotate Bearer tokens, especially if team members with access leave your organization.
• Restrict third-party access. Only add verified partners to your authorized_third_parties list and review it regularly.
• Monitor the audit log. Use the dashboard’s audit log to track API access patterns and detect anomalies.

Example: server-side verification

Node.js

const COMPANY_ID = process.env.ECONSENT_COMPANY_ID;
const PROPERTY_ID = process.env.ECONSENT_PROPERTY_ID;

async function verifyConsent(certificateId, consentText) {
  const response = await fetch('https://api.econsent.org/api/verify/match', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      company_id: COMPANY_ID,
      property_id: PROPERTY_ID,
      certificate_id: certificateId,
      consent: consentText,
    }),
  });

  return response.json();
}

Python

import os
import requests

COMPANY_ID = os.getenv('ECONSENT_COMPANY_ID')
PROPERTY_ID = os.getenv('ECONSENT_PROPERTY_ID')

def verify_consent(certificate_id, consent_text):
    response = requests.post(
        'https://api.econsent.org/api/verify/match',
        json={
            'company_id': COMPANY_ID,
            'property_id': PROPERTY_ID,
            'certificate_id': certificate_id,
            'consent': consent_text,
        },
    )
    return response.json()

PHP

<?php
$companyId = getenv('ECONSENT_COMPANY_ID');
$propertyId = getenv('ECONSENT_PROPERTY_ID');

function verifyConsent($certificateId, $consentText) {
    global $companyId, $propertyId;

    $ch = curl_init('https://api.econsent.org/api/verify/match');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'company_id' => $companyId,
        'property_id' => $propertyId,
        'certificate_id' => $certificateId,
        'consent' => $consentText,
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}
?>

Tip

For the complete Verification API documentation with all three endpoints and response formats, see the Verification API reference.