API Documentation
Complete reference for the Speare Self-Booking API
Getting Started
Partner API
Resources
Overview
The Speare Self-Booking API enables partners to create and manage insurance cases for patient bookings. All endpoints use JSON for requests and responses.
Base URL: https://behandlingsdekning.no//api/v1
Authentication
The API uses API key authentication. Include your API key in the request header:
X-API-Key: your-api-key-hereRate Limiting
To ensure fair usage, the API implements rate limiting:
- Public endpoints: 100 requests per minute
- Authenticated endpoints: 500 requests per minute
- Login endpoints: 5 requests per 15 minutes
Error Responses
All errors follow a consistent JSON format:
{
"error": "Invalid API key",
"statusCode": 401,
"details": {
"code": "INVALID_API_KEY"
}
}Cases Endpoints
POST/cases
Create a new insurance case for patient booking.
Request Body:
{
"partnerCaseId": "CASE-123",
"patientFirstName": "Ola",
"patientLastName": "Nordmann",
"patientEmail": "ola@example.no",
"patientPhone": "+47 12345678",
"injuryDate": "2024-01-15",
"injuryDescription": "Ryggskade etter bilulykke",
"treatmentType": "fysioterapi",
"bookingDeadline": "2024-02-15"
}Response:
{
"id": 1,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"partnerId": 1,
"partnerCaseId": "CASE-123",
"status": "pending_patient_action",
"createdAt": "2024-01-20T10:00:00Z"
}GET/cases
List all cases for authenticated partner.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
page | number | Page number (default: 1) |
limit | number | Items per page (default: 20, max: 100) |
status | string | Filter by status |
sort | string | Sort field:direction (e.g., createdAt:desc) |
GET/cases/:uuid
Get case details by UUID. No authentication required - patients access their cases via this endpoint.
PUT/cases/:uuid
Update case status and booking details. Limited fields available for public access.
Request Body:
{
"status": "booked",
"bookingDetails": {
"clinic": "Klinikk Oslo",
"appointmentDate": "2024-01-25",
"appointmentTime": "14:30",
"address": "Storgata 1, 0155 Oslo"
}
}Partner Authentication
POST/partners/auth
Validate API key and get partner details.
Request Body:
{
"apiKey": "your-api-key"
}Webhooks (Coming Soon)
Partners can register webhooks to receive real-time updates about case status changes. This feature is planned for a future release.
HTTP Status Codes
| Code | Description |
|---|---|
200 | Successful request |
201 | Resource created successfully |
400 | Bad request - Invalid input data |
401 | Unauthorized - Invalid or missing API key |
403 | Forbidden - Access denied |
404 | Not found - Resource doesn't exist |
429 | Too many requests - Rate limit exceeded |
500 | Internal server error |
Case Status Values
| Status | Description |
|---|---|
pending_patient_action | Waiting for patient to book appointment |
booked | Patient has successfully booked |
deadline_expired | Booking deadline has passed |
assistance_requested | Patient requested help with booking |
recalled | Case recalled by partner |
archived | Case archived |
error | Error processing case |
Need Help?
For technical support or questions about the API, contact our development team at tech@spearehelse.no