LLM.txt

# Seamlr Integration Context

## What is Seamlr?
Seamlr is a workforce staffing platform that matches candidates with shifts.
Scheduling providers integrate with Seamlr to fill their shifts with qualified candidates.

## Integration Model
- Provider → Seamlr: Webhooks notify Seamlr of shift changes
- Seamlr → Provider: REST API calls to fetch details and sync assignments
- All operations are initiated by Seamlr. The provider does not poll Seamlr.

## Data Ownership
| Data Type             | Source of Truth | Sync Direction    |
|-----------------------|-----------------|-------------------|
| Shift times, location | Provider        | Provider → Seamlr |
| Number of positions   | Provider        | Provider → Seamlr |
| Candidate assignments | Seamlr          | Seamlr → Provider |
| Candidate profiles    | Seamlr          | Seamlr → Provider |
| Booking status        | Seamlr          | Seamlr → Provider |

## Webhook Events (Provider → Seamlr)

POST https://api.seamlr.com/webhooks/scheduling-provider
Authorization: Bearer {seamlr_token}
Content-Type: application/json

### Event Types
- shift.create - New shift available for staffing
- shift.update - Shift details changed
- shift.delete - Shift cancelled

### Payload Schema
{
  "event": "shift.create" | "shift.update" | "shift.delete",
  "providerId": "uuid",       // Your provider ID from Seamlr
  "content": {
    "shiftId": "string"       // Your shift identifier
  },
  "traceId": "uuid"           // For request correlation
}

## Required Provider API Endpoints

All endpoints require:
- Authorization: Bearer {provider_token}
- Header: X-Seamlr-Provider-Id: {providerId}

### GET /shifts/{shiftId}
Returns shift details.

Response:
{
  "id": "string",
  "outletId": "string",
  "roleId": "string",
  "startTime": "ISO8601",
  "endTime": "ISO8601",
  "breakMinutes": number,
  "numberOfPositions": number,
  "assignedCandidates": [
    {
      "id": "string",
      "personalNumber": "string"  // Swedish personnummer (YYYYMMDD-XXXX)
    }
  ],
  "status": "open" | "filled" | "cancelled",
  "description": "string | null",
  "createdAt": "ISO8601",
  "updatedAt": "ISO8601"
}

### GET /candidates?personalNumber={personnummer}
Search for candidate by Swedish personal number.
Returns array of matching candidates (empty if not found).

Response:
[
  {
    "id": "string",
    "personalNumber": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phone": "string"
  }
]

### POST /candidates
Create a new candidate in provider system.

Request:
{
  "personalNumber": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string"
}

Response: Same as candidate object above with assigned id.

### PUT /shifts/{shiftId}/assign/{candidateId}
Assign candidate to shift.

Response:
{
  "success": true,
  "shiftId": "string",
  "candidateId": "string",
  "assignedAt": "ISO8601"
}

### DELETE /shifts/{shiftId}/assign/{candidateId}
Unassign candidate from shift.

Response: 204 No Content

### DELETE /shifts/{shiftId}
Cancel/delete a shift (when cancelled from Seamlr).

Response: 204 No Content

### GET /outlets
List available outlets/locations.

Response:
[
  {
    "id": "string",
    "name": "string",
    "address": "string | null"
  }
]

### GET /roles
List available roles/positions.

Response:
[
  {
    "id": "string",
    "name": "string"
  }
]

## Entity Mapping

Before activation, map provider entities to Seamlr:
- Outlets → Seamlr Workplaces (by name or address)
- Roles → Seamlr Competences (by name)

## Authentication

Two tokens are exchanged during setup:
1. Seamlr Token - Provider uses to send webhooks to Seamlr
2. Provider Token - Seamlr uses to call Provider API

Both are Bearer tokens in Authorization header.

## Data Flow Examples

### Shift Created in Provider
1. Provider sends webhook: shift.create
2. Seamlr queues event
3. Seamlr calls GET /shifts/{id}
4. Seamlr creates internal job
5. Seamlr matches and notifies candidates

### Candidate Assigned in Seamlr
1. Candidate accepts job in Seamlr
2. Seamlr calls GET /candidates?personalNumber=...
3. If not found: Seamlr calls POST /candidates
4. Seamlr calls PUT /shifts/{id}/assign/{candidateId}

### Shift Cancelled in Seamlr
1. Employer cancels in Seamlr
2. Seamlr calls DELETE /shifts/{id}
3. Provider sends echo webhook (ignored by Seamlr)

## Error Handling

- 4xx errors: Seamlr logs and may alert
- 5xx errors: Seamlr retries with exponential backoff
- Webhook acknowledgment: Respond 200 OK immediately, process async

## Swedish Personal Number Format

Format: YYYYMMDD-XXXX (12 digits with hyphen)
Example: 19900101-1234

Used as unique identifier for candidates across systems.
Using This Context

Copy the text block above and paste it into your AI assistant’s context when:
Building webhook handlers for Seamlr
Implementing the required API endpoints
Debugging integration issues
Understanding the data flow between systems
For complete documentation, see the Integration Guide.