{"openapi":"3.1.0","info":{"title":"CareLynx Open API","version":"1.0.0-beta-2","description":"HTTP gateway over the CareLynx Core API for approved third-party integrators.\n\n## Authenticating\n\nEvery request needs an API key, sent in the **`x-api-key`** header. There is\nno login step, no token exchange and no expiry — the key *is* the credential.\n\n```bash\ncurl -H \"x-api-key: clx_live_your_key_here\" \\\n     https://openapi.carelynxapp.com/api/v1/clients/{id}\n```\n\nTo run a request against the API from your browser, use the interactive\n[Swagger UI](/api/v1/docs): click **Authorize**, paste your key, and the\nheader is added to every \"Try it out\" call.\n\nKeys look like `clx_live_…` (or `clx_test_…` for a non-production\ndeployment). CareLynx issues them — they cannot be self-served — and each key\nis bound to exactly one customer instance, so the key alone determines whose\ndata you see. There is no tenant parameter to set, and no way to reach another\ncustomer's data with it.\n\nTreat the key as a password: send it only over HTTPS, keep it out of source\ncontrol, query strings and logs. If one leaks, ask CareLynx to rotate it —\nrotation issues a new key and invalidates the old one immediately.\n\n## Scopes\n\nKeys carry `careLynx/read`, `careLynx/write`, or both. Every endpoint\npublished today is a read and needs `careLynx/read`.\n\n## When a request is refused\n\n| Status | Meaning | What to do |\n| --- | --- | --- |\n| `401` | The key is missing, unrecognised, or revoked. | Check the `x-api-key` header is present and the key is current. Re-sending will not help. |\n| `403` | The key is valid but lacks the scope this endpoint needs. `error` is `insufficient_scope` and `required_scope` names the one it needs. | Ask CareLynx to widen the key. |\n| `404` | No such record in your customer instance. | Check the identifier. |\n| `429` | Too many requests. | Back off and retry. |\n| `502` | The gateway reached CareLynx and got an error back. | Transient — retry. If it persists, contact CareLynx with the time of the request. |","x-logo":{"url":"/assets/carelynx-logo.svg","altText":"CareLynx","backgroundColor":"transparent"}},"servers":[{"url":"/","description":"This deployment"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your CareLynx-issued API key, e.g. `clx_live_…`. Paste the key itself — no `Bearer` prefix and no quotes. It is sent as the `x-api-key` header on every request."}},"schemas":{"ClientSummary":{"type":"object","properties":{"uuid":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000"},"firstName":{"type":["string","null"],"example":"Sumiko"},"lastName":{"type":["string","null"],"example":"EMMERICH"},"dob":{"type":["string","null"],"example":"1963-10-05"},"crn":{"type":["string","null"],"example":"CRN1"}},"required":["uuid","firstName","lastName","dob","crn"]},"ClientListResponse":{"type":"object","properties":{"clients":{"type":"array","items":{"$ref":"#/components/schemas/ClientSummary"}}},"required":["clients"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"Not Found"},"error_description":{"type":"string"},"required_scope":{"type":"string","example":"careLynx/write"}},"required":["error"]},"CreatedBy":{"type":"object","properties":{"name":{"type":["string","null"],"example":"Jane Nurse"},"userId":{"type":["string","null"],"example":"42"}},"required":["name","userId"]},"DischargeInfo":{"type":"object","properties":{"isDischarged":{"type":"boolean","description":"True only when the client has left: a respite discharge, a plain discharge, or funeral/other. A hospital discharge leaves this false — see `reason`.","example":false},"isDeceased":{"type":"boolean","example":false},"reason":{"type":["string","null"],"enum":["deceased","discharge","other","hospital_discharge","hospital_discharge_emergency","hospital_discharge_not_emergency","respite_discharge"],"example":"hospital_discharge"},"date":{"type":["string","null"],"example":"2026-02-01"},"comment":{"type":["string","null"],"example":"Transferred to hospital"},"departureDetails":{"type":["string","null"],"example":"Ambulance"},"otherDetails":{"type":["string","null"],"example":"Family notified"},"placeOfDeath":{"type":["string","null"],"example":null}},"required":["isDischarged","isDeceased","reason","date","comment","departureDetails","otherDetails","placeOfDeath"]},"AdmissionType":{"type":"object","properties":{"type":{"type":"string","example":"Permanent"},"fromDate":{"type":["string","null"],"example":null},"toDate":{"type":["string","null"],"example":null}},"required":["type","fromDate","toDate"]},"ServiceProviderRef":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":["string","null"],"example":"Acme Care"}},"required":["id","name"]},"ClientDetails":{"type":"object","properties":{"uuid":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000"},"clientId":{"type":["string","null"],"example":"CL-00042"},"firstName":{"type":["string","null"],"example":"Sumiko"},"lastName":{"type":["string","null"],"example":"EMMERICH"},"middleName":{"type":["string","null"],"example":null},"preferredName":{"type":["string","null"],"example":"Adsy"},"myAgedCareId":{"type":["string","null"],"example":"AC-991"},"careRecipientId":{"type":["string","null"],"example":"CR-771"},"crn":{"type":["string","null"],"example":"CRN1"},"dob":{"type":["string","null"],"example":"1963-10-05"},"sex":{"type":["string","null"],"enum":["male","female","intersex","not_stated"],"example":"female"},"createdOn":{"type":"string","example":"2026-08-27T06:07:53.859Z"},"createdBy":{"$ref":"#/components/schemas/CreatedBy"},"discharge":{"$ref":"#/components/schemas/DischargeInfo"},"status":{"type":["string","null"],"example":"Grandfathered"},"admissionType":{"$ref":"#/components/schemas/AdmissionType"},"archived":{"type":"boolean","example":false},"bedNumber":{"type":["string","null"],"example":"12A"},"commencementDate":{"type":["string","null"],"example":"2026-03-02T00:00:00.000Z"},"serviceProvider":{"$ref":"#/components/schemas/ServiceProviderRef"}},"required":["uuid","clientId","firstName","lastName","middleName","preferredName","myAgedCareId","careRecipientId","crn","dob","sex","createdOn","createdBy","discharge","status","admissionType","archived","bedNumber","commencementDate","serviceProvider"]},"ClientResponse":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/ClientDetails"}},"required":["client"]},"ClassificationLevel":{"type":"object","properties":{"fundingType":{"type":["string","null"],"description":"The funding type this level was recorded against. Null on legacy records captured before levels were stored per funding type.","example":"Support at Home (SAH)"},"level":{"type":"string","example":"SAH - Classification 5"}},"required":["fundingType","level"]},"ClientClassification":{"type":"object","properties":{"clientType":{"type":["string","null"],"example":"Homecare"},"fundingTypes":{"type":"array","items":{"type":"string"},"description":"Every funding type recorded against the client. Empty when none is recorded.","example":["Support at Home (SAH)","NDIS"]},"classificationLevels":{"type":"array","items":{"$ref":"#/components/schemas/ClassificationLevel"},"description":"Classification levels, each paired with its funding type. Empty when none is recorded, and shorter than `fundingTypes` because most funding types carry no level."},"fundingAllocationDate":{"type":["string","null"],"example":"2026-03-02"},"careNeedsExceedFunding":{"type":["boolean","null"],"description":"Whether the client's care needs exceed their funded level. Null means the question has not been answered, which is not the same as false.","example":false},"group":{"type":["string","null"],"description":"Labelled \"Facility\" on residential instances.","example":"Northside"},"subgroup":{"type":["string","null"],"description":"Labelled \"Wing\" on residential instances.","example":"Team A"},"eolStatus":{"type":"string","enum":["NOT_EOL","EOL_RECOGNISED","EOL_DYING","NOT_SET","DECEASED"],"description":"The client's end-of-life status. `NOT_SET` means it has never been recorded.","example":"NOT_EOL"}},"required":["clientType","fundingTypes","classificationLevels","fundingAllocationDate","careNeedsExceedFunding","group","subgroup","eolStatus"]},"ClientClassificationResponse":{"type":"object","properties":{"classification":{"$ref":"#/components/schemas/ClientClassification"}},"required":["classification"]}},"parameters":{}},"paths":{"/api/v1/clients":{"get":{"tags":["Clients"],"operationId":"listClients","summary":"List clients","description":"Returns every current client (care recipient) in the CareLynx customer instance the caller is scoped to, as a summary: `uuid`, first and last name, date of birth and CRN. Use the `uuid` with `GET /api/v1/clients/{id}` to read the full record.\n\nArchived and discharged clients are excluded unless `includeInactive=true`. A hospitalised client is not a discharged one and is always listed — CareLynx models hospitalisation as a stay, not a departure.\n\nThe response is not paginated: the whole current caseload comes back in one call, ordered by last name, then first name, then `uuid`.","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false"],"description":"Set to `true` to include archived and discharged clients. Omitted or `false` returns the current caseload only.","example":"true"},"required":false,"name":"includeInactive","in":"query"}],"responses":{"200":{"description":"Every client matching the request, as summaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientListResponse"}}}},"400":{"description":"Bad request — invalid query / path parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — the request lacks valid credentials: no `x-api-key`, an unknown key, a revoked key, or (when bearer JWT is required) a missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — the key authenticated but is not permitted this operation. `error` is `insufficient_scope` and `required_scope` names the scope it lacks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — no record matches the identifier for this customer instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Bad gateway — downstream Core API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clients/{id}":{"get":{"tags":["Clients"],"operationId":"getClient","summary":"Get client details","description":"Returns the details of a single client (care recipient) in the CareLynx customer instance the caller is scoped to. The identifier may be the client's CareLynx UUID, the customer's own client number where one is recorded, or the client's CRN. Which of the latter two a customer records varies by instance. Only the UUID is guaranteed unique: if a client number or CRN matches more than one client, the request is refused with 409 rather than resolved arbitrarily.","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"The client's CareLynx UUID, the customer's own client number (client ID), or the client's CRN. Only the UUID is guaranteed to identify a single client; a client number or CRN that matches more than one is refused with 409.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Client details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"400":{"description":"Bad request — invalid query / path parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — the request lacks valid credentials: no `x-api-key`, an unknown key, a revoked key, or (when bearer JWT is required) a missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — the key authenticated but is not permitted this operation. `error` is `insufficient_scope` and `required_scope` names the scope it lacks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — no record matches the identifier for this customer instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — the identifier matches more than one client in this customer instance. `client_id` and `crn` are recorded by the customer and are not guaranteed unique; the client `uuid` always resolves to a single record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Bad gateway — downstream Core API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clients/{id}/classification":{"get":{"tags":["Clients"],"operationId":"getClientClassification","summary":"Get client classification","description":"Returns how a single client is funded and classified, and where they sit in the customer's own structure — client type, funding types, classification levels, funding allocation date, whether care needs exceed funding, group and subgroup, and end-of-life status. The identifier may be the client's CareLynx UUID, the customer's own client number where one is recorded, or the client's CRN. Which of the latter two a customer records varies by instance. Only the UUID is guaranteed unique: if a client number or CRN matches more than one client, the request is refused with 409 rather than resolved arbitrarily.","security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"The client's CareLynx UUID, the customer's own client number (client ID), or the client's CRN. Only the UUID is guaranteed to identify a single client; a client number or CRN that matches more than one is refused with 409.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Client classification and placement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientClassificationResponse"}}}},"400":{"description":"Bad request — invalid query / path parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — the request lacks valid credentials: no `x-api-key`, an unknown key, a revoked key, or (when bearer JWT is required) a missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — the key authenticated but is not permitted this operation. `error` is `insufficient_scope` and `required_scope` names the scope it lacks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — no record matches the identifier for this customer instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — the identifier matches more than one client in this customer instance. `client_id` and `crn` are recorded by the customer and are not guaranteed unique; the client `uuid` always resolves to a single record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Bad gateway — downstream Core API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}