Partner API

Partner Media Delivery API

Public guide for technology partners · Last updated August 8, 2026

How to get started

Request a sandbox from /integrations. Benefits Interactive issues a test key, maps your externalEmployerId values, and provides your base URL. This page is the public contract only — it does not contain credentials.

1. Overview

Benefits Interactive is the benefits literacy layer on top of HR, payroll, and enrollment systems. Partners embed approved media in their own UX. BI remains the system of record for creation, approval, publishing, and delivery authorization.

Controlled delivery means:

Catalog responses contain metadata only (no playback URLs).
Delivery responses mint an expiring URL when the partner is ready to play or download.
Partners never receive durable CDN URLs in catalog responses.

This API does not:

Process enrollment transactions or carrier feeds
Sync employee identity (SCIM, SSO passthrough)
Accept writeback (completions, analytics into BI)
Allow asset authoring or publishing

2. Authentication

Every request must include:

Authorization: Bearer bi_live_<secret>
Content-Type: application/json

Environment	Key prefix
Production	`bi_live_`
Sandbox	`bi_test_`

Secrets are shown once at issuance. Store them securely. Revoked or unknown keys return 401 with code invalid_api_key.

3. Base URL & versioning

Production and sandbox base URLs are provided during onboarding (for example https://app.benefitsinteractive.com).

v1 routes are prefixed with /api/integrations/v1. Breaking changes increment the path version. Optional JSON fields may be added without a version bump.

v2 (/api/integrations/v2) adds slides and infographic PDF delivery; v1 remains video + audio only.

4. Endpoints

4.1 List media for an employer

GET /api/integrations/v1/groups/{externalEmployerId}/media

Path: externalEmployerId — your employer id (mapped at onboarding).

Query: limit (default 25, max 50), cursor, kinds (default video,audio), locale (optional BCP 47).

{
  "externalEmployerId": "acme-corp-2026",
  "groupId": "WC0126",
  "items": [
    {
      "learningResourceId": 1042,
      "kind": "video",
      "title": "Your 2026 Medical Plan Overview",
      "subtitle": "Plain-language walkthrough",
      "category": "Medical",
      "locale": null,
      "updatedAt": "2026-06-15T18:22:11.000Z",
      "videoProjectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "audioVariants": []
    }
  ],
  "nextCursor": null
}

Catalog items never include deliveryUrl or long-lived CDN URLs.

4.2 Get a single media item

GET /api/integrations/v1/media/{learningResourceId}?externalEmployerId={externalEmployerId}

externalEmployerId is required for entitlement checks.

4.3 Mint a delivery URL

POST /api/integrations/v1/media/{learningResourceId}/delivery

{
  "externalEmployerId": "acme-corp-2026",
  "variant": "summary"
}

For audio, variant is summary or deep. Omit variant for video.

{
  "learningResourceId": 1042,
  "kind": "video",
  "variant": null,
  "deliveryUrl": "https://example.cdn/embed/…",
  "expiresAt": "2026-07-07T01:20:00.000Z",
  "contentType": "text/html",
  "deliveryMode": "embed"
}

Default TTL is 300 seconds from mint time.
Mint when the user starts playback — not when listing the catalog.
Do not persist deliveryUrl; store learningResourceId + externalEmployerId instead.
If expired, mint again with a new POST.

5. Media kinds

kind	Delivery
`video`	Short-lived embed URL
`audio`	Short-lived download / stream URL
`slides` / `infographic`	v2 — short-lived PDF URL

Only published, assigned media for the mapped employer is deliverable. Drafts are never exposed.

6. Errors

{
  "error": {
    "code": "forbidden",
    "message": "You do not have access to this employer."
  }
}

Prefer the stable code for programmatic handling.

HTTP	code	When
400	`invalid_request`	Malformed JSON or missing fields
401	`invalid_api_key`	Missing, invalid, or revoked key
403	`forbidden`	Valid key but not entitled
404	`unknown_group` / `not_found` / `not_published`	Unmapped employer or unavailable asset
409	`unsupported_kind`	Kind not enabled for partner
429	`rate_limited`	Too many requests
500	`internal_error`	Unexpected server error

7. Rate limits

Defaults (per API key; may be adjusted at onboarding):

Catalog + detail: 120 requests / minute
Delivery mint: 60 requests / minute

When limited, expect 429 with Retry-After.

8. Onboarding

Request sandbox via /integrations.
Receive test key + employer mappings for a pilot group.
Implement catalog → detail → delivery → playback against v1.
Complete security review (no durable CDN URLs in catalog caches).
Go live with a production key and production mappings.

Support: support@benefitsinteractive.app