{"openapi":"3.1.0","info":{"title":"SIA Intelligence API","version":"2026-09-23","description":"Put an absence case to SIA from your own system and read the same analysis the portal shows. Organisation plan, with the API module on. Every response is Cache-Control: no-store. See /docs/api for the prose reference."},"servers":[{"url":"/","description":"Your own workspace host, for example https://sia.example.com"}],"security":[{"bearer":[]}],"paths":{"/api/v1/intelligence":{"post":{"operationId":"analyseCase","summary":"Analyse a case","description":"Opens the case in the workspace (owned by the key owner) and runs the portal analysis on it, with the company memory. Counts as 5 units of usage when the category is answer. Needs the analysis:write scope. When the triage sends the case straight to an expert (boundary sia_human, and no factor other than unclear), no analysis runs and nothing is charged: the answer is 202 with the case awaiting confirmation and SIA's expert recommendation. No expert ticket is opened through the API; the case owner confirms the expert review in SIA at confirm_url. Without expert review in the workspace that triage is refused with 422 expert_review_unavailable.","x-scopes":["analysis:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique value of yours per case. The same key and body within 24 hours replays the stored response.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceRequest"}}}},"responses":{"200":{"description":"The analysis.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceResponse"}}}},"202":{"description":"The triage sent the case straight to an expert: it awaits confirmation by a person in SIA. No analysis, no ticket, no charge.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertRouteResponse"}}}},"400":{"description":"Error. code is one of: invalid_json, invalid_request, invalid_idempotency_key, client_employer_unknown.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error. code is one of: missing_key, invalid_key, key_expired.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Error. code is one of: credits, trial_expired.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error. code is one of: insufficient_scope, plan_required, module_disabled, workspace_suspended, workspace_deleted.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error. code is one of: idempotency_in_progress, reference_taken, no_case_owner.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error. code is one of: idempotency_mismatch, free_text_confirmation, pii_detected, expert_review_unavailable.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error. code is one of: rate_limited, spend_cap.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error. code is one of: analysis_failed.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Error. code is one of: provider_timeout.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/intelligence/{case_id}":{"get":{"operationId":"readAnalysis","summary":"Read a stored analysis","description":"The newest analysis of one case of the key workspace. Costs nothing. Needs the analysis:read scope.","x-scopes":["analysis:read"],"parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The stored analysis, in the shape the POST returned.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceResponse"}}}},"202":{"description":"A case on the direct route to an expert that still awaits confirmation in SIA, in the shape the POST returned.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertRouteResponse"}}}},"401":{"description":"Error. code is one of: missing_key, invalid_key, key_expired.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error. code is one of: insufficient_scope, plan_required, module_disabled, workspace_suspended, workspace_deleted.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error. code is one of: case_not_found.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error. code is one of: rate_limited, spend_cap.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error. code is one of: analysis_failed.","headers":{"SIA-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"analysis.completed":{"post":{"summary":"An analysis has finished, through the API or on screen","description":"Signed with SIA-Signature (t=<unix time>,v1=<hex HMAC-SHA256 of \"t.body\">). Headers SIA-Event, SIA-Delivery and SIA-API-Version are sent too.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","api_version","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"const":"analysis.completed"},"created_at":{"type":"string","format":"date-time"},"api_version":{"type":"string"},"data":{"$ref":"#/components/schemas/AnalysisCompletedData"}}}}}},"responses":{"200":{"description":"Any 2xx within 5 seconds counts as delivered."}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key, sia_… . Scopes: analysis:write, analysis:read."}},"headers":{"ApiVersion":{"description":"The API version of this response.","schema":{"type":"string","const":"2026-09-23"}}},"schemas":{"IntelligenceRequest":{"type":"object","properties":{"case_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"absence_day":{"type":"integer","minimum":0,"maximum":2000},"description":{"type":"string","minLength":20,"maxLength":4000},"previous_interventions":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},"manager_context":{"type":"string","maxLength":1000},"occupational_health_status":{"type":"string","maxLength":500},"language":{"type":"string","enum":["nl","en"]},"reference":{"type":"string","maxLength":64},"employee_role":{"type":"string","maxLength":80},"first_sick_day":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"events":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["full_recovery","relapse","partial_recovery","second_track","deskundigenoordeel","loonsanctie","employment_ended_tv"]},"date":{"type":"string"},"sanction_weeks":{"type":"integer","minimum":1,"maximum":52}},"required":["kind","date"]}},"confirm_free_text":{"type":"boolean"},"triage":{"type":"object","properties":{"factors":{"maxItems":7,"type":"array","items":{"type":"string","enum":["medical","conflict","workload","performance","organisational","personal","unclear"]}},"boundary":{"maxItems":6,"type":"array","items":{"type":"string","enum":["self","company_doctor","labour_expert","legal","mediation","sia_human"]}},"next_step_owner":{"anyOf":[{"type":"string","enum":["case_manager","manager","hr","external"]},{"type":"null"}]},"signals":{"type":"object","propertyNames":{"type":"string","maxLength":80},"additionalProperties":{"type":"string","enum":["yes","no","unknown"]}}}},"department":{"type":"string","minLength":1,"maxLength":120},"absence_type":{"type":"string","enum":["full","partial"]},"client_employer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["case_date","description","language"]},"IntelligenceResponse":{"type":"object","properties":{"case_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"category":{"type":"string","enum":["answer","insufficient_information","expert_judgement_required"]},"assessment":{"type":"string"},"reasoning":{"type":"string"},"action":{"type":"string"},"deadline":{"anyOf":[{"type":"object","properties":{"date":{"type":"string"},"label":{"type":"string"},"days_from_case_date":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["date","label","days_from_case_date"],"additionalProperties":false},{"type":"null"}]},"risk":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"version":{"type":"string"},"article":{"type":"string"},"status":{"type":"string","enum":["legal_requirement","official_guidance","sia_best_practice","expert_judgement","licensed_source","sia_concept"]}},"required":["title","version","article","status"],"additionalProperties":false}},"confidence":{"type":"string","enum":["low","medium","high"]},"escalation":{"type":"object","properties":{"required":{"type":"boolean"},"reason":{"type":["string","null"]},"to":{"anyOf":[{"type":"string","enum":["expert_review"]},{"type":"null"}]}},"required":["required","reason","to"],"additionalProperties":false},"missing_information":{"type":"array","items":{"type":"string"}},"ai_generated":{"type":"boolean","const":true},"ai_notice":{"type":"string"},"ai_blocks":{"type":"array","items":{"type":"string","enum":["category","assessment","reasoning","action","deadline","risk","confidence","escalation","missing_information"]}},"credits":{"type":"object","properties":{"charged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["charged","balance"],"additionalProperties":false},"timeline":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"rule":{"type":"string"},"week":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"due":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string","enum":["upcoming","due_soon","overdue","done"]},"basis":{"type":"string"},"shiftedBy":{"type":"array","items":{"type":"string","enum":["relapse","loonsanctie","non_working_day"]}},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["key","rule","week","due","status","basis"],"additionalProperties":false}},{"type":"null"}]}},"required":["case_id","category","assessment","reasoning","action","deadline","risk","sources","confidence","escalation","missing_information","ai_generated","ai_notice","ai_blocks","credits","timeline"],"additionalProperties":false},"ExpertRouteResponse":{"type":"object","properties":{"case_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reference":{"type":"string"},"status":{"type":"string","const":"awaiting_confirmation"},"analysis":{"type":"null"},"expert_recommendation":{"type":"object","properties":{"recommended":{"type":"boolean","const":true},"reason":{"type":"string","const":"triage_expert_needed"},"reason_text":{"type":"string"},"confirmation_required":{"type":"boolean","const":true},"next_step":{"type":"string"},"confirm_url":{"type":"string"}},"required":["recommended","reason","reason_text","confirmation_required","next_step","confirm_url"],"additionalProperties":false},"credits":{"type":"object","properties":{"charged":{"type":"number","const":0},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["charged","balance"],"additionalProperties":false},"timeline":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"rule":{"type":"string"},"week":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"due":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string","enum":["upcoming","due_soon","overdue","done"]},"basis":{"type":"string"},"shiftedBy":{"type":"array","items":{"type":"string","enum":["relapse","loonsanctie","non_working_day"]}},"until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["key","rule","week","due","status","basis"],"additionalProperties":false}},{"type":"null"}]}},"required":["case_id","reference","status","analysis","expert_recommendation","credits","timeline"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}},"required":["field","message"],"additionalProperties":false}},"hits":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"kind":{"type":"string","enum":["diagnosis","gender","age","third_party"]},"term":{"type":"string"}},"required":["field","kind","term"],"additionalProperties":false}},"credits":{"type":"object","properties":{"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"required":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["balance","required"],"additionalProperties":false}},"required":["error","code"],"additionalProperties":{}},"AnalysisCompletedData":{"type":"object","properties":{"case_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"case_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"category":{"type":"string"},"confidence":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}]},"escalation_required":{"type":"boolean"},"source":{"type":"string","enum":["api","app"]},"ai_generated":{"type":"boolean","const":true},"ai_notice":{"type":"string"}},"required":["case_id","case_date","category","confidence","escalation_required","source","ai_generated","ai_notice"],"additionalProperties":false}}}}