Retain API

The Retain API lets you programmatically choose which session recordings to keep and convert to MP4 video. This is designed for lead generation companies and other businesses that only want to retain recordings for sessions that matter — for example, leads that were actually sold — rather than auto-retaining every session.

Each retained session costs $0.10 and is billed from your prepaid wallet on a pay-as-you-go basis.

Base URL

https://api.econsent.org

Authentication

All endpoints require a Bearer token with the vzew_retention permission in the Authorization header:

Authorization: Bearer YOUR_INTEGRATION_TOKEN

You can generate an integration token from your dashboard under Settings > Integrations.

---

POST /api/integrations/:companyId/retain/:sessionId

Retain a single session recording and queue it for MP4 video conversion. The session’s retention_status is set to retained and rrweb_to_video_status is set to pending, which triggers the conversion pipeline.

URL parameters

Parameter	Type	Required	Description
companyId	string	Yes	Your company ID
sessionId	string	Yes	The session ID to retain

Example

curl

curl -X POST https://api.econsent.org/api/integrations/comp-abc/retain/sess-12345 \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN"

Node.js

const API_TOKEN = process.env.ECONSENT_INTEGRATION_TOKEN;

async function retainSession(companyId, sessionId) {
  const response = await fetch(
    `https://api.econsent.org/api/integrations/${companyId}/retain/${sessionId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
      },
    }
  );

  const data = await response.json();

  if (data.success) {
    console.log('Session retained:', data.sessionId);
    console.log('Status:', data.status);
    console.log('Cost charged:', data.cost_charged);
    console.log('Remaining balance:', data.remaining_balance);
  }

  return data;
}

// Retain a single session
await retainSession('comp-abc', 'sess-12345');

Python

import os
import requests

API_TOKEN = os.environ["ECONSENT_INTEGRATION_TOKEN"]
BASE_URL = "https://api.econsent.org"

def retain_session(company_id: str, session_id: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/api/integrations/{company_id}/retain/{session_id}",
        headers={"Authorization": f"Bearer {API_TOKEN}"},
    )
    response.raise_for_status()
    return response.json()

# Retain a single session
result = retain_session("comp-abc", "sess-12345")
print(f"Retained: {result['sessionId']}, cost: ${result['cost_charged']}")

Success response (200)

{
  "success": true,
  "sessionId": "sess-12345",
  "status": "queued_for_conversion",
  "cost_charged": 0.10,
  "remaining_balance": 95.40
}

Response fields

Field	Type	Description
success	boolean	Whether the retention was processed
sessionId	string	The session ID that was retained
status	string	Always queued_for_conversion on success
cost_charged	number	Amount charged for this retention ($0.10)
remaining_balance	number	Your remaining wallet balance after the charge

Tip

Once a session is retained, the MP4 conversion pipeline picks it up automatically. Conversion typically completes within a few minutes depending on recording length.

---

POST /api/integrations/:companyId/retain/batch

Retain multiple session recordings in a single request. Each session is charged individually at $0.10 per session.

URL parameters

Parameter	Type	Required	Description
companyId	string	Yes	Your company ID

Request body

Parameter	Type	Required	Description
session_ids	string[]	Yes	Array of session IDs to retain (max 100)

Example

curl

curl -X POST https://api.econsent.org/api/integrations/comp-abc/retain/batch \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_ids": [
      "sess-12345",
      "sess-67890",
      "sess-abcde",
      "sess-fghij",
      "sess-klmno"
    ]
  }'

Node.js

const API_TOKEN = process.env.ECONSENT_INTEGRATION_TOKEN;

async function retainBatch(companyId, sessionIds) {
  const response = await fetch(
    `https://api.econsent.org/api/integrations/${companyId}/retain/batch`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ session_ids: sessionIds }),
    }
  );

  const data = await response.json();

  if (data.success) {
    console.log(`Retained: ${data.retained}, Failed: ${data.failed}`);
    console.log(`Total cost: $${data.total_cost}`);
    console.log(`Remaining balance: $${data.remaining_balance}`);
  }

  return data;
}

// Retain a batch of sessions after selling the leads
const soldLeadSessions = [
  'sess-12345',
  'sess-67890',
  'sess-abcde',
  'sess-fghij',
  'sess-klmno',
];

await retainBatch('comp-abc', soldLeadSessions);

Python

import os
import requests

API_TOKEN = os.environ["ECONSENT_INTEGRATION_TOKEN"]
BASE_URL = "https://api.econsent.org"

def retain_batch(company_id: str, session_ids: list[str]) -> dict:
    response = requests.post(
        f"{BASE_URL}/api/integrations/{company_id}/retain/batch",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json",
        },
        json={"session_ids": session_ids},
    )
    response.raise_for_status()
    return response.json()

# Retain sessions for leads that were sold today
sold_sessions = ["sess-12345", "sess-67890", "sess-abcde"]
result = retain_batch("comp-abc", sold_sessions)
print(f"Retained: {result['retained']}, Total cost: ${result['total_cost']}")

Success response (200)

{
  "success": true,
  "retained": 5,
  "failed": 1,
  "total_cost": 0.50,
  "remaining_balance": 94.90,
  "results": [
    { "sessionId": "sess-12345", "success": true, "status": "queued_for_conversion" },
    { "sessionId": "sess-67890", "success": true, "status": "queued_for_conversion" },
    { "sessionId": "sess-abcde", "success": true, "status": "queued_for_conversion" },
    { "sessionId": "sess-fghij", "success": true, "status": "queued_for_conversion" },
    { "sessionId": "sess-klmno", "success": true, "status": "queued_for_conversion" },
    { "sessionId": "sess-invalid", "success": false, "error": "Session not found" }
  ]
}

Response fields

Field	Type	Description
success	boolean	Whether the batch request was processed
retained	number	Number of sessions successfully retained
failed	number	Number of sessions that failed to retain
total_cost	number	Total amount charged for all successful retentions
remaining_balance	number	Your remaining wallet balance after all charges
results	array	Per-session results with individual success/failure status

Caution

The batch endpoint processes up to 100 sessions per request. If you need to retain more, split them into multiple batch calls. Partial failures do not roll back successful retentions — you are only charged for sessions that succeed.

---

Typical integration flow

For lead generation companies, the typical workflow is:

1. Capture consent — eConsent records the session automatically when a consumer fills out your form
2. Post lead to buyer — Your system sends the lead to the buyer/advertiser
3. Buyer accepts lead — Once the lead is sold and accepted, call the Retain API
4. MP4 generated — The recording is converted to MP4 and stored for long-term compliance

// Example: retain session after lead is sold
async function onLeadSold(companyId, sessionId) {
  const response = await fetch(
    `https://api.econsent.org/api/integrations/${companyId}/retain/${sessionId}`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_TOKEN}` },
    }
  );

  const data = await response.json();
  if (!data.success) {
    console.error('Failed to retain session:', data.error);
  }
}

This approach means you only pay $0.10 per lead that matters, rather than retaining every session at scale.

---

Rate limits

Endpoint	Limit
Single retain	500 requests per minute
Batch retain	500 requests per minute

Exceeding the rate limit returns a 429 response. Implement exponential backoff in your integration.

---

Error responses

Status	Meaning	Example scenario
401	Unauthorized	Invalid or expired integration token
402	Payment required	Insufficient wallet balance to cover the retention cost
404	Not found	Session ID does not exist or does not belong to your company
409	Conflict	Session has already been retained
429	Rate limited	Exceeded 500 requests per minute

Error response format

{
  "success": false,
  "error": "Insufficient wallet balance",
  "required": 0.10,
  "current_balance": 0.05
}

Note

A 402 error means your wallet balance is too low. Top up your wallet from the dashboard at app.econsent.org under Billing > Wallet.

---

Pricing

Action	Cost
Retain single session	$0.10 per session
Retain batch (per session)	$0.10 per session

All costs are deducted from your prepaid wallet balance. The batch endpoint charges per successful retention — failed sessions within a batch are not charged.

---

Next steps

• Authentication. Set up your integration token
• Verification API. Verify consent certificates
• Retention Management. Configure auto-retain settings
• Video Conversion. Learn about MP4 conversion and storage