DevelopersCorporate Benefit REST APIs

Corporate Benefit REST APIs

Corporate organization endpoints for declaration list processing and employee health benefit termination.

POST/v1/corporate/declarations

Submits an employee declaration list for automated corporate census reconciliation, bulk onboarding, benefit plan tier assignment, and real-time eligibility synchronization across HMO underwriters and provider networks.

Required HTTP Headers

Header	Example Value	Description
Authorization	Bearer sk_live_corp_...	Corporate organization API key
X-Manticore-Idempotency-Key	decl_batch_2026_10	Prevents accidental duplicate staff list submission
Content-Type	application/json	JSON request format

Request Fields (Body)

Field	Type	Required	Description
corporate_id	UUID	YES	Unique identifier of the corporate employer organization
declaration_month	string	YES	Billing period in YYYY-MM format (e.g. 2026-10)
declaration_type	string	YES	FULL_CENSUS or MONTHLY_ADDITIONS
enrollees	EnrolleeDeclaration[]	YES	Array of employee records and linked dependents for benefit activation

POST /v1/corporate/declarations

curl -X POST https://api.manticore.ng/v1/corporate/declarations \
  -H "Authorization: Bearer sk_live_corp_7a9f82d1c0..." \
  -H "X-Manticore-Idempotency-Key: decl_batch_oct_2026_01" \
  -H "Content-Type: application/json" \
  -d '{
    "corporate_id": "c7a821be-4ef2-432c-9889-a5cb5b06afe4",
    "declaration_month": "2026-10",
    "declaration_type": "MONTHLY_ADDITIONS",
    "enrollees": [
      {
        "employee_id": "EMP-94812",
        "first_name": "Babajide",
        "last_name": "Adekunle",
        "work_email": "b.adekunle@accessholdings.ng",
        "phone": "08031234567",
        "date_of_birth": "1988-06-14",
        "gender": "MALE",
        "plan_tier": "GOLD_EXECUTIVE",
        "primary_provider_id": "hosp_lag_st_nicholas_01",
        "dependents": [
          {
            "relationship": "SPOUSE",
            "first_name": "Amina",
            "last_name": "Adekunle",
            "date_of_birth": "1991-03-22",
            "gender": "FEMALE"
          }
        ]
      }
    ]
  }'

Response (200 OK)

{
  "status": "PROCESSED",
  "batch_id": "decl_b9f4a180-87ef-4613-bc75-47201c10972b",
  "corporate_id": "c7a821be-4ef2-432c-9889-a5cb5b06afe4",
  "total_records_received": 142,
  "new_enrollees_activated": 18,
  "enrollees_updated": 124,
  "rejected_records": 0,
  "digital_qr_cards_issued": 18,
  "network_hospitals_notified": 48,
  "effective_coverage_start": "2026-10-01T00:00:00Z",
  "processed_at": "2026-10-16T08:30:15.102Z"
}

Authentication & Scope

Bearer Token (Requires CORPORATE_ADMIN or HR_BENEFITS scope)