TRUE CARE SYSTEM • API DOCUMENTATION
Employee API
Create, retrieve, update, search, and manage Provider employee records, workforce status, roles, and Sandata-related identifiers.
Create, retrieve, update, search, and manage Provider employee records, workforce status, roles, and Sandata-related identifiers.
Employee API responses may include sensitive Provider, workforce, Individual, clinical, financial, or operational information. Production access must remain authenticated, Provider-scoped, role-authorized, purpose-limited, and auditable. Sample values below are demonstrations only.
Functional Scope
The Employee API supports the approved workflows shown in the True Care System user interface while centralizing validation and security enforcement in the backend. Client applications should never reproduce or bypass server-side authorization rules.
Primary Endpoint Groups
| Method | Route | General Purpose |
|---|---|---|
GET | /employees | Search and list Provider employees. |
POST | /employees | Create an employee record. |
GET | /employees/:id | Return one employee record. |
PATCH | /employees/:id | Update approved employee fields. |
PATCH | /employees/:id/status | Change employment or account status. |
Request Controls
- Require a valid authenticated session for protected routes.
- Resolve Provider scope from the authorized identity and server-managed context.
- Validate identifiers, dates, status values, and enumerated fields.
- Reject cross-Provider access even when a record identifier is known.
- Apply role and permission checks before reading or changing data.
- Record applicable view, create, update, delete, export, or approval activity.
Example List Request
GET /api/employee?page=1&limit=25&status=ACTIVE
Authorization: Bearer <access-token>Example Success Response
{
"success": true,
"message": "Employee records returned.",
"data": {
"items": [],
"page": 1,
"limit": 25,
"total": 0
},
"requestId": "demo-request-id"
}Common Validation and Error Conditions
| Condition | Expected handling |
|---|---|
| Unauthenticated request | Return an authentication error without exposing account details. |
| Insufficient role permission | Return a forbidden response and record security-relevant evidence where required. |
| Cross-Provider identifier | Do not disclose whether the record exists outside the authorized Provider scope. |
| Invalid field or date | Return a validation response with safe, actionable corrections. |
| Record conflict | Reject duplicates, overlaps, or invalid state transitions according to business rules. |
| Unexpected server failure | Return a safe generic error with a request identifier; preserve diagnostics only in protected logs. |
Audit and HIPAA Expectations
Where the request accesses or changes PHI or sensitive operational data, the audit record should preserve the authorized Provider, user or actor, target record, module, action, timestamp, request context, outcome, and other approved metadata.
Implementation Checklist
- Controller or route contract defined.
- Request DTO or schema validation defined.
- Provider filter enforced in the service or data-access layer.
- Role authorization verified.
- Sensitive response fields reviewed.
- Audit behavior tested.
- Success, validation, forbidden, not-found, and conflict cases tested.
- Documentation and Test Catalog updated with the code change.
Troubleshooting
Records are missing
Verify Provider scope, filters, record status, date range, pagination, and role permissions.
A request returns forbidden
Confirm the user's assigned role and permission. Do not bypass the backend guard.
A save returns validation errors
Compare the request body with the approved DTO, enum values, required fields, effective dates, and business-state requirements.