Developer Reference

API Documentation
v4.8

Full reference for the CalibraSync REST API. Authenticate, validate respondents, retrieve attestation records, and manage project configurations programmatically.

Base URL: https://api.calibrasync.com/v4 REST · JSON · HTTPS only Avg. response: 4.1ms
Getting Started
Authentication Rate Limits Error Codes
Core Endpoints
POST /validate GET /attestation/{id} POST /project GET /audit-log
Webhooks
S2S Callbacks Event Types
Getting Started
Authentication

All API requests require a Bearer token issued upon account provisioning. Tokens are scoped to a specific client account and may be further restricted by IP allowlist at the account level. Never expose your API key in client-side code. All traffic must be transmitted over HTTPS; HTTP requests are rejected at the gateway.

// Authorization header — required on every request
Authorization: Bearer cs_live_k9Xm2p...your_key_here
// Example: cURL
curl -X POST https://api.calibrasync.com/v4/validate \
  -H "Authorization: Bearer cs_live_k9Xm2p..." \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "proj_abc123", "respondent_uid": "RID_88219F" }'
Core Endpoints
POST /v4/validate Primary attestation entry point

Initiates the full five-layer Calibra Protocol evaluation for a single respondent. Returns a disposition, a Calibra-ID (on COMPLETE), and per-layer scores. Average response time: 4.1ms.

Request Parameters
ParameterTypeRequiredDescription
project_idstringRequiredYour CalibraSync project identifier. Created via POST /project.
respondent_uidstringRequiredThe respondent identifier assigned by your sample source or survey platform.
ip_addressstringRequiredIPv4 or IPv6 address of the respondent at entry. Used for SIVT Layer 01 classification.
user_agentstringRequiredFull browser user-agent string. Used in GIVT detection and fingerprint construction.
panel_sourcestringOptionalPanel or exchange identifier. Enables cross-source deduplication logic.
behavioral_payloadobjectOptionalClient-side behavioral telemetry (mouse events, keystroke intervals). Increases Layer 03 scoring accuracy.
open_end_responsesarrayOptionalArray of open-ended response strings for Layer 04 Semantic AI Audit scoring.
Response — 200 OK (COMPLETE)
{
  "calibra_id": "F9E2-8201-3A4C-B9D1",
  "disposition": "COMPLETE",
  "overall_score": 0.94,
  "layer_scores": {
    "sivt": "pass",
    "fingerprint": "unique",
    "behavioral": 0.91,
    "semantic": 0.97
  },
  "latency_ms": 3.8,
  "timestamp": "2026-03-29T14:22:11.394Z"
}
Response Codes
200 COMPLETE
All layers passed. Calibra-ID issued. Record respondent as valid complete.
200 SECURITY
SIVT or fingerprint layer failure. Do not count as complete. No charge.
200 PRE-TERM
Behavioral or semantic threshold exceeded. Terminate survey. No charge.
200 DUPLICATE
Fingerprint matched in deduplication database. Terminate. No charge.
401
Invalid or expired API key. Check Authorization header.
429
Rate limit exceeded. Implement exponential backoff. See rate limits.
GET /v4/attestation/{calibra_id} Retrieve full attestation record

Returns the complete attestation record for a Calibra-ID — including all layer scores, disposition chain, and audit metadata. Used for post-fieldwork verification, compliance reporting, and supplier dispute resolution.

// GET /v4/attestation/F9E2-8201-3A4C-B9D1
{
  "calibra_id": "F9E2-8201-3A4C-B9D1",
  "project_id": "proj_abc123",
  "disposition": "COMPLETE",
  "audit_chain": [
    { "layer": "SIVT", "result": "pass", "latency_ms": 0.4 },
    { "layer": "FINGERPRINT", "result": "unique", "latency_ms": 1.2 },
    { "layer": "BEHAVIORAL", "score": 0.91, "latency_ms": 1.8 },
    { "layer": "SEMANTIC", "score": 0.97, "latency_ms": 0.4 }
  ],
  "created_at": "2026-03-29T14:22:11.394Z",
  "retention_expires": "2029-03-29T00:00:00.000Z"
}
Server-to-Server Callbacks
S2S Webhook Configuration

CalibraSync supports server-to-server callback URLs for real-time disposition notifications. When a respondent's attestation resolves, the callback fires immediately — before the respondent is redirected to your completion page. This enables your platform to make server-side quota and incentive decisions based on the disposition, without exposing API logic to the client.

// S2S Callback Payload — fired on every disposition
POST https://your-survey-platform.com/s2s/calibra-callback
{
  "event": "attestation.resolved",
  "calibra_id": "F9E2-8201-3A4C-B9D1",
  "disposition": "COMPLETE",
  "overall_score": 0.94,
  "project_id": "proj_abc123",
  "respondent_uid": "RID_88219F",
  "signature": "sha256=d4f2a1..." // HMAC-SHA256 for verification
}
Security Note
Always verify the signature header using your webhook secret before processing any callback. This prevents spoofed disposition events from manipulating your quota or incentive logic.