API Reference

ExpressConsent provides a REST API for programmatically accessing your organization's consent data. You can retrieve domains, snapshots, and manage lead validation sharing between organizations.

The API is currently read-only. Creating, updating, or deleting resources is not yet supported.

Base URL

https://api.expressconsent.com/

Authentication

All requests require an API key in the x-api-key header:

x-api-key: <your-api-key>

Getting an API Key

Sign in to your ExpressConsent dashboard
Navigate to Settings → API Keys
Click Generate key and copy the value (format: <keyId>.<secret>)

API keys are shown only once during creation. If compromised, revoke the key and generate a new one.

Organization Endpoints

List Domains

Get all domains owned by your organization.

Request

GET /domains HTTP/1.1
Host: api.expressconsent.com
x-api-key: <your-api-key>

Response - 200 OK

{
  "domains": ["example.com", "shop.example.com", "landing.mysite.io"]
}

Name
domains
Type
string[]
Description
Array of domain identifiers owned by your organization.

curl -H "x-api-key: $API_KEY" \
  "https://api.expressconsent.com/domains"

Snapshot Endpoints

List Domain Snapshots

Retrieve paginated consent snapshots for a specific domain with optional filtering.

Request

GET /domains/{domainId}/snapshots HTTP/1.1
Host: api.expressconsent.com
x-api-key: <your-api-key>

Query Parameters

Name
pageSize
Type
number
Description
Results per page (1-100, default: 20)
Name
pageToken
Type
string
Description
Document ID to start after (for pagination)
Name
order
Type
'asc' | 'desc'
Description
Sort direction by createdAt (default: 'desc')
Name
metadataKey
Type
string
Description
Filter by custom metadata key presence
Name
metadataValue
Type
string
Description
Filter by custom metadata value (requires metadataKey)

Response - 200 OK

{
  "snapshots": [
    {
      "transactionId": "tx_abc123def456",
      "contentType": "image/png",
      "downloadURL": "https://storage.googleapis.com/...",
      "customMetadata": {
        "phoneNumber": "555-0123",
        "formName": "newsletter-signup",
        "campaignId": "summer2025"
      },
      "domain": "example.com",
      "createdAt": "2025-04-15T10:30:45.123Z",
      "webhookSuccessfullySentAt": "2025-04-15T10:30:47.456Z",
      "signerCanonicalIp": "198.51.100.23",
      "signerUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
      "affiliateTags": ["org_456def789"],
      "anuraData": {
        "result": "allow",
        "ruleId": 12345,
        "score": 95
      }
    }
  ],
  "nextPageToken": "tx_next789ghi012"
}

Response Fields

Name
transactionId
Type
string
Description
Unique transaction identifier for the snapshot
Name
contentType
Type
string
Description
MIME type of the snapshot file
Name
downloadURL
Type
string
Description
Signed URL for downloading the snapshot (valid 7 days)
Name
customMetadata
Type
object
Description
Custom data captured with the snapshot
Name
domain
Type
string
Description
Domain where the snapshot was taken
Name
createdAt
Type
string
Description
ISO 8601 timestamp of snapshot creation
Name
webhookSuccessfullySentAt
Type
string?
Description
Timestamp of successful webhook delivery (if configured)
Name
signerCanonicalIp
Type
string?
Description
Canonical client IP captured during the sign step, when available
Name
signerUserAgent
Type
string?
Description
Client User-Agent captured during the sign step, when available
Name
affiliateTags
Type
string[]?
Description
Organization IDs with access to this snapshot
Name
anuraData
Type
object?
Description
Fraud detection results (if Anura integration enabled)

# Get recent snapshots
curl -H "x-api-key: $API_KEY" \
  "https://api.expressconsent.com/domains/example.com/snapshots?pageSize=50"

# Filter by metadata
curl -H "x-api-key: $API_KEY" \
  "https://api.expressconsent.com/domains/example.com/snapshots?metadataKey=campaignId&metadataValue=summer2025"

# Pagination
curl -H "x-api-key: $API_KEY" \
  "https://api.expressconsent.com/domains/example.com/snapshots?pageToken=tx_next789ghi012"

When nextPageToken is present in the response, use it in the next request's pageToken parameter to fetch additional results.

Get Single Snapshot

Retrieve a specific snapshot by its transaction ID.

Request

GET /snapshots/{transactionId} HTTP/1.1
Host: api.expressconsent.com
x-api-key: <your-api-key>

Response - 200 OK

{
  "snapshot": {
    "transactionId": "tx_abc123def456",
    "contentType": "image/png",
    "downloadURL": "https://storage.googleapis.com/...",
    "customMetadata": {
      "phoneNumber": "555-0123",
      "formName": "newsletter-signup"
    },
    "domain": "example.com",
    "createdAt": "2025-04-15T10:30:45.123Z",
    "webhookSuccessfullySentAt": "2025-04-15T10:30:47.456Z",
    "signerCanonicalIp": "198.51.100.23",
    "signerUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "affiliateTags": ["org_456def789"],
    "anuraData": {
      "result": "allow",
      "ruleId": 12345
    }
  }
}

Name
transactionId
Type
path param
Description
The unique transaction ID of the snapshot to retrieve

curl -H "x-api-key: $API_KEY" \
  "https://api.expressconsent.com/snapshots/tx_abc123def456"

ExpressConsent allows you to share lead validations with other organizations for verification purposes. This is useful for lead validation, compliance verification, or B2B consent transfers.

Share a Lead Validation

Generate a secure, time-limited URL to share a lead validation with another organization.

Request

GET /shareLeadValidation/{leadValidationId} HTTP/1.1
Host: api.expressconsent.com
x-api-key: <your-api-key>

Response - 200 OK

{
  "shareUrl": "https://api.expressconsent.com/collectLeadValidation/abc123token456def",
  "expiresAt": "2025-05-14T10:30:45.123Z"
}

Name
leadValidationId
Type
path param
Description
The unique identifier of the lead validation to share
Name
shareUrl
Type
string
Description
Secure URL the recipient organization will use to collect the lead validation
Name
expiresAt
Type
string
Description
ISO 8601 timestamp when the share token expires (30 days from creation)

curl -H "x-api-key: $API_KEY" \
  "https://api.expressconsent.com/shareLeadValidation/lv_abc123def456"

Share URLs expire after 30 days. You can share the same shareUrl with multiple organizations - each recipient will need their own API key to collect it.

Collect Shared Lead Validation

Collect a lead validation that was shared with your organization.

Request

GET /collectLeadValidation/{token} HTTP/1.1
Host: api.expressconsent.com
x-api-key: <recipient-api-key>

Response - 200 OK

{
  "success": true
}

Name
token
Type
path param
Description
The unique token from the share URL provided by the sending organization

curl -H "x-api-key: $RECIPIENT_API_KEY" \
  "https://api.expressconsent.com/collectLeadValidation/abc123token456def"

Collection Behavior

When you successfully collect a shared lead validation:

Duplication: The lead validation and all associated snapshots are copied to your organization
Access: You gain permanent access to all snapshots in the lead validation
Marking: The original lead validation is marked as "collected" in both organizations
Tracking: Your organization ID is added to the affiliate tags for tracking
Reusable: The share URL can be collected by multiple different organizations until it expires

Important: You cannot collect lead validations that your own organization shared. The original organization retains access to their data after sharing.

Error Handling

All errors return JSON with an error message describing the issue.

Error Response

{
  "error": "Invalid API key"
}

Common Status Codes

Name
400 Bad Request
Description
Invalid request parameters or attempting to collect your own shared lead validation
Name
401 Unauthorized
Description
Missing or invalid API key
Name
404 Not Found
Description
Resource doesn't exist or doesn't belong to your organization
Name
409 Conflict
Description
Resource conflict (e.g., your organization has already collected this lead validation)
Name
410 Gone
Description
Share token has expired
Name
500 Internal Server Error
Description
Unexpected server error - retry the request

Code Examples

JavaScript/Node.js Helper

API Helper Function

class ExpressConsentAPI {
  constructor(apiKey) {
    this.apiKey = apiKey
    this.baseURL = 'https://api.expressconsent.com'
  }

  async request(path, options = {}) {
    const response = await fetch(`${this.baseURL}${path}`, {
      headers: {
        'x-api-key': this.apiKey,
        'Content-Type': 'application/json',
        ...options.headers,
      },
      ...options,
    })

    if (!response.ok) {
      const error = await response.json()
      throw new Error(error.error || response.statusText)
    }

    return response.json()
  }

  // Get organization domains
  async getDomains() {
    return this.request('/domains')
  }

  // Get snapshots for a domain
  async getSnapshots(domainId, options = {}) {
    const params = new URLSearchParams(options)
    return this.request(`/domains/${domainId}/snapshots?${params}`)
  }

  // Get single snapshot
  async getSnapshot(transactionId) {
    return this.request(`/snapshots/${transactionId}`)
  }

  // Share a lead validation
  async shareLeadValidation(leadValidationId) {
    return this.request(`/shareLeadValidation/${leadValidationId}`)
  }

  // Collect shared lead validation
  async collectLeadValidation(token) {
    return this.request(`/collectLeadValidation/${token}`)
  }
}

Next: Webhooks

API Reference

Base URL

Authentication

Getting an API Key

Organization Endpoints

List Domains

Request

Response - 200 OK

Snapshot Endpoints

List Domain Snapshots

Request

Query Parameters

Response - 200 OK

Response Fields

Get Single Snapshot

Request

Response - 200 OK

Lead Validation Sharing

Share a Lead Validation

Request

Response - 200 OK

Collect Shared Lead Validation

Request

Response - 200 OK

Collection Behavior

Error Handling

Error Response

Common Status Codes

Code Examples

JavaScript/Node.js Helper

API Helper Function