Docs

Everything you need to integrate.

REST API for ingesting enrollment data, generating X12 5010 transactions, transmitting to carriers, and reconciling acknowledgments. Idempotent. Webhook-driven. OpenAPI 3.1 spec available.

On this page

01 Getting started

Four steps to your first transmission.

  1. 01 Sign up and receive your API key (prefixed with vel_).
  2. 02 Configure your carrier connections via the dashboard or POST /api/v1/carriers.
  3. 03 Submit enrollment data as JSON — we handle X12 generation, validation, and transmission.
  4. 04 Monitor status via webhooks or polling on GET /enrollments/:id.
02 API reference

Every endpoint, with curl + JS.

Base URL: https://velora-edi.vercel.app/api/v1

Auth: Include your API key in the X-API-Key header.

POST /enrollments

Submit enrollment transactions (ADD, CHANGE, TERMINATE, REINSTATE).

cURL
curl -X POST https://velora-edi.vercel.app/api/v1/enrollments \
  -H "X-API-Key: vel_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "uuid-of-carrier-connection",
    "transaction_type": "ADD",
    "member": {
      "subscriber_id": "EMP001",
      "first_name": "John",
      "last_name": "Smith",
      "ssn": "123-45-6789",
      "date_of_birth": "1990-05-15",
      "gender": "M",
      "address": {
        "street": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701"
      }
    },
    "employment": {
      "hire_date": "2025-01-15",
      "employee_id": "ACME-001"
    },
    "coverage": {
      "line": "medical",
      "plan_name": "Gold PPO 500",
      "tier": "employee_only",
      "effective_date": "2026-01-01"
    }
  }'
Response (201 Created)
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "RECEIVED",
  "transaction_type": "ADD",
  "external_ref": "ENR-1001",
  "created_at": "2026-04-12T14:30:00.000Z"
}

GET /enrollments

List transactions with filtering by status, date, and pagination.
cURL
curl "https://velora-edi.vercel.app/api/v1/enrollments?status=ACCEPTED&limit=10" \
  -H "X-API-Key: vel_your_api_key_here"
Response (200 OK)
{
  "data": [
    {
      "id": "f47ac10b-...",
      "status": "ACCEPTED",
      "transaction_type": "ADD",
      "member_data": { "member": { "first_name": "John", "last_name": "Smith" } },
      "created_at": "2026-04-12T14:30:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10
}

GET /carriers

List configured carrier connections.
cURL
curl "https://velora-edi.vercel.app/api/v1/carriers" \
  -H "X-API-Key: vel_your_api_key_here"
Response (200 OK)
{
  "data": [
    {
      "id": "...",
      "carrier_name": "UnitedHealthcare",
      "carrier_code": "UHC",
      "payer_id": "87726",
      "transmission_method": "SFTP",
      "is_active": true
    }
  ]
}

POST /enrollments/raw

Submit enrollments in your native HRIS / payroll shape. A saved mapping transforms each record into the canonical schema before the normal pipeline runs. Use this if you’d rather not re-shape data in your own code.
cURL
curl -X POST https://velora-edi.vercel.app/api/v1/enrollments/raw \
  -H "X-API-Key: vel_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mapping_name": "Workday export",
    "carrier": "AETNA",
    "group_number": "GRP-ACME-001",
    "records": [
      {
        "employeeId": "EMP-000123",
        "legalName": { "first": "Jane", "last": "Doe" },
        "tax": { "ssn": "123-45-6789" },
        "dateOfBirth": "03/15/1985",
        "personal": { "sex": "Female" },
        "homeAddress": {
          "line1": "742 Evergreen Terrace",
          "city": "Springfield", "stateCode": "or", "postal": "97403"
        },
        "benefits": [{ "plan": "Gold PPO", "effective": "2026/01/01" }]
      }
    ]
  }'
Response (201 Created)
{
  "data": {
    "batch_id": "f47ac10b-...",
    "records_received": 1,
    "status": "QUEUED",
    "transaction_ids": ["..."],
    "job_id": "..."
  },
  "mapping_id": "...",
  "records_submitted": 1,
  "mapping_errors": [],
  "mapping_error_count": 0
}

POST /mappings

Create a mapping from 1–10 sample records. Claude proposes the transform rules; the platform contract-tests the result before returning. High-confidence proposals with clean contract tests auto-confirm; lower-confidence ones are saved as drafts for admin review. You can also POST a hand-written mapping directly instead of sample_records.
cURL
curl -X POST https://velora-edi.vercel.app/api/v1/mappings \
  -H "X-API-Key: vel_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Workday export",
    "sample_records": [
      { "employeeId": "...", "legalName": { "first": "..." }, "...": "..." }
    ]
  }'
Response (201 Created)
{
  "data": {
    "id": "...",
    "name": "Workday export",
    "mapping": { "...": "..." },
    "confidence": 0.94,
    "is_confirmed": true,
    "auto_confirmed": true,
    "notes": ["Inferred MDY date format from samples"],
    "unmapped_targets": [],
    "contract_test": { "ok": true, "synthesized_count": 1, "issues": [] }
  }
}
Related: GET /mappings, GET/PATCH/DELETE /mappings/:id, POST /mappings/:id/test, POST /mappings/:id/chat (preview-only AI edit), POST /mappings/:id/chat/apply, and GET/POST /mappings/:id/versions for history and rollback.

GET /inbox

Aggregated rejections, mapping errors, and shape-drift warnings, each with an AI-proposed fix attached. Resolve individual items via POST /inbox/:id/resolve.
cURL
curl "https://velora-edi.vercel.app/api/v1/inbox?status=open" \
  -H "X-API-Key: vel_your_api_key_here"
Response (200 OK)
{
  "data": [
    {
      "id": "...",
      "category": "mapping_error",
      "severity": "error",
      "title": "Mapping \"Workday export\" produced no usable records",
      "suggestion": {
        "kind": "mapping_patch",
        "summary": "Change date_of_birth transform to ymd_dash_to_iso",
        "confidence": 0.92
      },
      "status": "open",
      "created_at": "2026-04-14T16:10:02.000Z"
    }
  ],
  "total": 1
}

POST /carrier/signup

Public endpoint — no API key required. Creates a carrier account, mints a crr_-prefixed API key (shown once), and returns the next onboarding step. Rate-limited to 3 attempts per minute per IP.
cURL
curl -X POST https://velora-edi.vercel.app/api/v1/carrier/signup \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Health",
    "contact_name": "Pat Example",
    "contact_email": "pat@acmehealth.com",
    "carrier_code": "ACME",
    "transmission_method": "SFTP"
  }'
Response (201 Created)
{
  "data": {
    "carrier_config_id": "...",
    "api_key": "crr_...",
    "api_key_prefix": "crr_xxxxxxxx",
    "onboarding_state": "SIGNED_UP",
    "next_step": {
      "action": "upload_companion_guide",
      "endpoint": "POST /api/v1/carrier/companion-guide"
    }
  }
}
Follow-ups use the returned key: GET /carrier/me, POST /carrier/companion-guide (AI parses rules), PUT /carrier/transport (SFTP / API creds), and POST /carrier/sandbox — three clean sandbox runs auto-promote the carrier to ACTIVE.
Additional endpoints: GET /enrollments/:id, POST /enrollments/:id/retry, GET /batches/:id/content (fetch your stored 834), GET /analytics/dashboard, POST /webhooks/test. All endpoints return JSON. Errors follow RFC 7807 problem-details format.
03 Carrier integration

40 carriers pre-mapped.

Velora EDI supports SFTP, AS2, and REST API transmission methods. Each carrier connection is configured with companion-guide rules that enforce carrier-specific validation. Pre-mapped carriers include UnitedHealthcare, Cigna, Aetna, every Blue Cross plan, Kaiser Permanente, Humana, MetLife, Guardian, and more.

Companion guides can be uploaded as PDFs — our AI parses carrier-specific rules automatically and applies them during validation. New carriers self-onboard via POST /api/v1/carrier/signup and reach production status in under an hour after three clean sandbox runs.

Carrier directoryCarrier onboarding
04Security & compliance

The baseline that ships on every plan.

All PHI is encrypted at rest (AES-256-GCM) and in transit (TLS 1.2+). API keys are hashed with SHA-256 and never stored in plaintext. Rate limiting is enforced per-client via distributed Redis. Hash-chained audit logs capture every PHI access with IP, user ID, and timestamp.

Business Associate Agreement (BAA) is part of paid signup. See /baa for the full agreement, /security for the technical posture, and /hipaa for the compliance pillars.

Need more depth?

The OpenAPI 3.1 spec, TypeScript SDK type stubs, and webhook signing playground are all on the docs landing.

Get an API keyTalk to engineeringSee the demo