Overview

Spike Care OpenAPI Specification

Core Platform Concepts

Patient Plans

Patient Plans represent the insurance coverage associated with a specific patient. These records are immutable by design—once created, their key attributes cannot be modified through the API. To update plan information, you must archive the existing plan and create a new one. This ensures data integrity across all dependent verification processes.

Eligibility Verification

The platform automatically performs eligibility verifications for all active patients on a recurring basis, typically scheduled for the first day of each month. Each verification is specific to a single patient plan and confirms whether the insurance coverage remains active and valid.

Benefit Verification

Benefit verifications can be initiated on-demand for any patient plan, providing detailed coverage information including copayment amounts, deductible details, and other plan-specific benefits. The system also automatically generates annual benefit verifications for active patient plans at the beginning of each calendar year.

Escalation Management

When the verification process requires additional information or action from your team, the system creates an escalation within the Spike Care web portal. These escalations must be resolved through the web interface before processing can continue.

API Authentication

All API requests require authentication via Bearer token credentials. To generate an access token, navigate to the Spike Care Portal and create a token linked to your provider organization or management services organization (MSO). If you’re not yet a Spike Care customer, please visit our website to schedule a consultation and learn more about our platform capabilities.

Request Rate Limits

The API enforces rate limiting to ensure platform stability and fair resource allocation. Standard endpoints accept up to 120 requests per minute, while file upload operations are limited to 60 requests per minute. If your use case requires higher throughput, please contact our engineering team at [e-mail] to discuss options.

When your request rate exceeds the allowed threshold, the API returns a 429 status code with the following response:

{
  "message": "Rate limit exceeded. Please wait {X} seconds before trying again."
}

Every API response includes rate limit information in the following headers:

• X-RateLimit-Limit: Maximum requests allowed per minute for the endpoint
• X-RateLimit-Remaining: Remaining requests in the current time window
• X-RateLimit-Reset: Unix timestamp when the rate limit resets
• Retry-After: Seconds to wait before retrying (non-zero only when rate limited)

External Identifier Integration

The API supports external identifiers (source IDs) to facilitate integration with your existing systems. This feature eliminates the need to store Spike Care resource IDs in your database and enables idempotent upsert operations via PUT requests.

Source ID functionality is available for these resource types:

• Clinics (Providers)
• Service Locations
• Patients
• Patient Plans

You can query resources by source ID using the source_id query parameter, or create resources with a specific source ID by including it in the request body. To search for resources without an assigned source ID, pass null as the source_id parameter value.

Idempotent Request Handling

The platform provides two mechanisms for ensuring request idempotency: PUT endpoints and the Idempotency-Key header.

PUT Endpoint Semantics

PUT endpoints require a source_id in the request body and follow upsert semantics—if a resource with the specified source ID exists, it will be updated; otherwise, a new resource is created. This approach simplifies integration by removing the need to track Spike Care internal IDs.

Important: If you’re migrating existing data from the Spike Care web application to the API, you’ll need to backfill source IDs for all relevant resources before using PUT endpoints. Contact our team to coordinate this process, providing CSV files with the following formats:

• Clinics/Service Locations: source_id, name
• Patients: source_id, first_name, last_name, date_of_birth
• Patient Plans: source_id, patient_source_id, plan_order_number, member_id

Using PUT endpoints before completing the backfill may result in duplicate records or unintended archival of existing data.

Idempotency Key Header

For endpoints that support the Idempotency-Key header, you can provide a unique string (up to 255 characters) to ensure a request is processed exactly once. Subsequent requests with the same key will return the cached response from the initial request.

Key considerations:

• Idempotency guarantees apply only to successful (2XX) responses
• Keys are retained for 30 days before expiration
• Reusing a key with different request parameters or body content results in a 400 error

Resource Deletion Behavior

All DELETE operations in the API perform soft deletion, archiving the resource rather than permanently removing it from the system. Archived resources remain queryable through specific endpoints but are excluded from standard list operations.

Error Response Format

API errors return a JSON response with a descriptive message:

{
  "message": "{ERROR_DESCRIPTION}"
}

Certain error types, such as authentication failures (401), include an additional type field for programmatic error handling:

{
  "message": "{ERROR_DESCRIPTION}",
  "type": "{ERROR_TYPE}"
}

Standard HTTP error codes:

• 400: Invalid request parameters or body
• 401: Authentication failure
• 404: Resource not found
• 413: Request payload exceeds size limit
• 429: Rate limit exceeded

Paginated Responses

List endpoints implement keyset-based (cursor) pagination for efficient navigation through large result sets. Control pagination using these query parameters:

• limit: Number of results per page (1-100, defaults vary by endpoint)
• starting_after: Cursor to fetch the next page (ID of the last record from previous response)
• ending_before: Cursor to fetch the previous page (ID of the first record from previous response)

Paginated responses include these fields:

{
  "records": [],
  "has_more": true,
  "first_id": "0194a4ed-130d-775b-81fd-ca2b4eb618ce",
  "last_id": "0194a4ed-501d-7790-802e-404c23617954"
}

• records: Array of resource objects for the current page
• has_more: Boolean indicating whether additional pages exist
• first_id: ID of the first record in the current page
• last_id: ID of the last record in the current page

Development & Testing Environment

We provide isolated test accounts for integration development and quality assurance. To request a test environment, contact [e-mail] or reach out via your dedicated Slack channel.

Test accounts offer full API functionality with the following limitations:

• Background processing (benefit verifications, eligibility verifications) requires manual intervention by Spike Care staff to simulate completion
• Data is isolated from production systems

We strongly recommend thoroughly testing your implementation in a test environment before enabling production access. This includes validating patient and plan creation, and benefit verification workflows. For assistance with testing state transitions, contact the Spike Care team via Slack to manually advance verification records to completed states.

Integration Implementation Roadmap

1. Core Patient & Verification Management

Required Capabilities:

1. Determine your insurance provider identification strategy (see Insurance Provider Overview)
2. Implement patient create/update/retrieve operations
3. Implement patient plan create/update/retrieve operations
4. Implement benefit verification creation with status polling
5. Complete source ID backfill (if using PUT endpoints)

Essential Reading:

• Patient Plan Overview
• Benefit Verification Overview
• Insurance Provider Overview