AlayaCare Employees API
The Employees API from AlayaCare — 7 operation(s) for employees.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/alayacare-employees-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: External Employee Employees API
version: 1.0.8
description: "**AlayaCare IDs:**\nThe following terms are used to reference IDs that identify resources in AlayaCare:\n- employee_id\n- contact_id\n\n**External IDs**\nThe following terms are used to reference IDs that identify resources systems external to AlayaCare:\n- external_employee_id\n- external_contact_id\n\nExternal IDs are required to be unique.\nNo other assumptions are made regarding their format they are treated as strings.\n\n**Remarks**\n- All dates must be in ISO 8601 format with timezone data\n\n**Employee Status Considerations**\n- When updating the `status` of an employee to `terminated`, it is possible to add a `comment`. This `comment` is saved as an Employee Note with a `note_type` of type `terminated`.\n- Updating the `status` of an employee will have repercussions in the AlayaCare application. Please refer to this link for more information: \n https://alayacare.zendesk.com/hc/en-us/articles/360020774691\n"
servers:
- url: https://homecare.alayacare.ca/ext/api/v2/employees
tags:
- name: Employees
paths:
/employees:
get:
tags:
- Employees
summary: 'Get a list of employees.
'
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/branch'
- $ref: '#/components/parameters/status'
- name: filter
in: query
description: Substring search on profile attributes
schema:
type: string
- name: group
in: query
description: Filter by group ID, one or more using **OR**
style: form
explode: true
schema:
type: array
items:
type: integer
- name: department
in: query
description: 'Filter by department ID. For available departments
see resource `/departments`
'
schema:
type: integer
- name: designation
in: query
description: 'Filter by designation. For available designations
see resource `/designations`
'
schema:
type: string
responses:
'200':
description: A list of employees
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeList'
'401':
$ref: '#/components/responses/ErrorResponseAuthentication'
post:
tags:
- Employees
summary: 'Create an employee.
'
description: '- `branch_id` is optional, if omitted employee will be created in the default branch.
- `status` is optional, if omitted employee will be created with an `active` status.
- `branch_id` and `status` can only be set at creation.
- Only one of `profile_id` or a `demographics` object can be specified.
- Adding a `comment` when creating an employee with a `status` set to `terminated` is not supported by this endpoint. Any `comment` sent will be ignored.
'
responses:
'201':
$ref: '#/components/responses/SuccessResponseEmployeeCreate'
'409':
description: Conflict
content:
application/json:
example:
code: 409
message: 'Employee already exists with external ID: external_id_3'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 400
message: Field first_name is required in demographics
'401':
$ref: '#/components/responses/ErrorResponseAuthentication'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeCreate'
description: Employee definition in JSON format
required: true
/employees/{employee_id}:
parameters:
- name: employee_id
description: AlayaCare ID of the employee
in: path
required: true
schema:
type: string
get:
tags:
- Employees
summary: Get employee details using its AlayaCare ID
responses:
'200':
description: Employee details
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeDetails'
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
put:
tags:
- Employees
summary: Modify employee details using its AlayaCare ID
description: '* Changing the `branch_id` of an employee is not supported by this API. Any `branch_id` sent will be ignored.
* Changing the `status` of an employee is not supported by this endpoint. Any `status` sent will be ignored.
'
responses:
'200':
$ref: '#/components/responses/SuccessResponseEmployeeUpdate'
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeUpdate'
description: Object with fields to be updated
/employees/by_id/{external_employee_id}:
parameters:
- name: external_employee_id
description: External ID of the employee to retrieve
in: path
required: true
schema:
type: string
get:
tags:
- Employees
summary: 'Get employee using an external ID provided on creation
'
responses:
'200':
description: Employee details
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeDetails'
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
put:
tags:
- Employees
summary: 'Modify employee details using an external ID provided on creation
'
description: '* Changing the `branch_id` of an employee is not supported by this API. Any `branch_id` sent will be ignored.
* Changing the `status` of an employee is not supported by this endpoint. Any `status` sent will be ignored.
'
responses:
'200':
$ref: '#/components/responses/SuccessResponseEmployeeUpdate'
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeUpdate'
description: Object with fields to be updated
/employees/{employee_id}/status:
parameters:
- name: employee_id
description: AlayaCare ID of the employee
in: path
required: true
schema:
type: string
put:
tags:
- Employees
summary: 'Update employee status using its AlayaCare ID
'
description: '* A `comment` can only be set when updating an employee status to `terminated`.
'
responses:
'200':
$ref: '#/components/responses/SuccessResponseEmployeeUpdate'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 400
message: Field status is required
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeStatusUpdate'
description: Object with status to be updated
/employees/by_id/{external_employee_id}/status:
parameters:
- name: external_employee_id
description: External ID of the employee
in: path
required: true
schema:
type: string
put:
tags:
- Employees
summary: 'Update employee status using an external ID provided on creation
'
description: '* A `comment` can only be set when updating an employee status to `terminated`.
'
responses:
'200':
$ref: '#/components/responses/SuccessResponseEmployeeUpdate'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 400
message: Field status is required
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeStatusUpdate'
description: Object with status to be updated
/employees/{employee_id}/picture:
parameters:
- name: employee_id
description: AlayaCare ID of the employee
in: path
required: true
schema:
type: string
get:
tags:
- Employees
summary: Get employee profile picture pre-authorized URL.
parameters:
- $ref: '#/components/parameters/ttl'
responses:
'200':
description: Profile picture URL.
content:
application/json:
schema:
$ref: '#/components/schemas/ProfilePictureUrl'
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
/employees/by_id/{external_employee_id}/picture:
parameters:
- name: external_employee_id
description: External ID of the employee
in: path
required: true
schema:
type: string
get:
tags:
- Employees
summary: Get employee profile picture pre-authorized URL.
parameters:
- $ref: '#/components/parameters/ttl'
responses:
'200':
description: Profile picture URL.
content:
application/json:
schema:
$ref: '#/components/schemas/ProfilePictureUrl'
'404':
$ref: '#/components/responses/ErrorResponseEmployeeNotFound'
components:
schemas:
ErrorResponse:
description: Error response
type: object
properties:
code:
type: integer
description: Response code
message:
type: string
description: Detailed error message
required:
- code
- message
ProfilePictureUrl:
type: object
properties:
url:
description: Pre-authorized profile picture url.
type: string
example: https://place-hold.it/200
EmployeeUpdate:
description: AlayaCare employee entity data for creation
type: object
properties:
demographics:
$ref: '#/components/schemas/EmployeeDemographics'
external_id:
type: string
username:
type: string
example: john.smith
roles:
description: 'List of roles. Role objects have ID for convenience
of input, but only the IDs are used here. For valid IDs,
request /roles.
'
type: array
items:
type: object
properties:
id:
type: integer
example: 1
groups:
description: 'List of groups. Group objects have ID for convenience
of input, but only the IDs are used here. For valid IDs,
request /groups.
'
type: array
items:
type: object
properties:
id:
type: integer
example: 1
departments:
description: 'List of departments. Department objects have ID for convenience
of input, but only the IDs are used here. For valid IDs,
request /departments.
'
type: array
items:
type: object
properties:
id:
type: integer
example: 1
designation:
type: string
example: Nurse
payroll_number:
type: string
example: A123
seniority:
description: "The employee seniority value is determined by the Employee Seniority Type defined in the system settings. \nThis value must correspond to the selected type, which can be RANK, DATE, or NUMBER.\n"
type: string
example: 897563
max_biweekly_capacity:
type: number
example: 50.5
min_biweekly_capacity:
type: number
example: 20.5
max_weekly_capacity:
type: string
example: '24.5'
min_weekly_capacity:
type: string
example: '10'
max_daily_capacity:
type: string
example: 10
min_daily_capacity:
type: string
example: 2
default_availability:
type: string
description: 'Default employee''s availability. If not set, will inherit the branch default availability.
Accepted values: "available", "unavailable"
'
example: available
employment_type:
type: object
properties:
id:
type: integer
example: 1
timezone:
description: 'Timezone name in IANA format (iana.org/time-zones). If set to null, will inherit the branch timezone.
'
type: string
example: America/Toronto
EmployeeStatus:
description: 'Enum of the status of an employee
'
type: string
enum:
- active
- pending
- on_hold
- suspended
- terminated
- applicant
- rejected
- unknown
CostCentre:
description: Details of a cost centre
type:
- object
- 'null'
properties:
description:
type: string
description: Cost centre description
example: Montreal
id:
type: integer
description: Cost centre ID
example: 2
number:
type: string
description: Cost centre number for display in-app
example: '5555'
status:
type: string
description: Cost centre status
example: enabled
EmploymentType:
description: Employment Type
type: object
properties:
id:
type: integer
description: ID of the employment type
example: 1
name:
type: string
description: Name of employment type
example: Full time
required:
- id
BranchSummary:
description: Branch summary
type: object
properties:
id:
type: integer
description: ID of the branch
example: 1
name:
type: string
description: Name of the branch
example: Headquarters
EmployeeList:
allOf:
- $ref: '#/components/schemas/PaginatedList'
description: 'List of employees
'
type: object
properties:
items:
type: array
items:
allOf:
- $ref: '#/components/schemas/Employee'
properties:
branch:
$ref: '#/components/schemas/BranchSummary'
SuccessResponse:
description: Success response.
type: object
properties:
id:
type: integer
description: AlayaCare ID
external_id:
type:
- string
- 'null'
description: External ID
required:
- id
- external_id
Location:
description: Location information
type:
- object
- 'null'
properties:
lat:
type: number
description: latitude
example: 45.518
lon:
type: number
description: longitude
example: -73.582
zip:
type: string
description: postal code
example: H0H 0H0
Group:
description: AlayaCare group.
type: object
properties:
id:
type: integer
description: AlayaCare group ID
example: 1
name:
type: string
description: AlayaCare group name
example: Group 1
required:
- id
- name
Department:
description: AlayaCare department.
type: object
properties:
id:
type: integer
description: AlayaCare department ID
example: 1
name:
type: string
description: AlayaCare department name
example: Nursing
required:
- id
- name
Employee:
description: 'AlayaCare employee list view
'
type: object
properties:
id:
type: integer
example: 1
ac_id:
type: string
description: AlayaCare ID for display in-app
example: AC000000024
external_id:
type:
- string
- 'null'
example: external_id_1
profile_id:
type: integer
example: 7890
first_name:
type: string
example: John
last_name:
type:
- string
- 'null'
example: Smith
status:
$ref: '#/components/schemas/EmployeeStatus'
job_title:
type:
- string
- 'null'
email:
type: string
example: john@smith.com
phone:
type:
- string
- 'null'
example: '+15555555555'
phone_other:
type:
- string
- 'null'
example: '+15555555555'
designation:
type:
- string
- 'null'
departments:
type: array
items:
type: integer
description: ID of a department
_link:
type: string
EmployeeDemographics:
description: 'Collection of key/value pairs where keys are existing attributes in the employee profile, defined through the AlayaCare webapp.
On the example below default profile keys for the employee are used.
Example profile attributes:
+ `address_suite`: string
+ `address`: string
+ `birthday`: string
+ `city`: string
+ `company`: string
+ `country`: string
+ `department`: string
+ `email_preferred`: string
+ `email`: string
+ `employee_id`: string
+ `fax`: string
+ `first_name`: string
+ `gender`: string
+ `group`: string
+ `last_name`: string
+ `phone_main`: string
+ `phone_other`: string
+ `phone_personal`: string
+ `remarks`: string
+ `salutation`: string
+ `state`: string
+ `timeframe`: string
+ `title`: string
+ `zip`: string
+ `termination_date`: string
'
type: object
required:
- first_name
- last_name
- email
properties:
first_name:
type: string
last_name:
type: string
email:
type: string
format: email
location:
$ref: '#/components/schemas/Location'
example:
first_name: John
last_name: Doe
email: john@doe.com
salutation: Mr.
gender: M
EmployeeDetails:
description: AlayaCare employee entity
type: object
properties:
demographics:
$ref: '#/components/schemas/EmployeeDemographics'
id:
type: integer
ac_id:
type: string
description: AlayaCare ID for display in-app
example: AC000000024
external_id:
type:
- string
- 'null'
profile_id:
type: integer
example: 7890
branch_id:
type: integer
status:
$ref: '#/components/schemas/EmployeeStatus'
roles:
type: array
description: Employee roles
items:
$ref: '#/components/schemas/Role'
groups:
type: array
description: Employee groups
items:
$ref: '#/components/schemas/Group'
departments:
type: array
description: Employee departments
items:
$ref: '#/components/schemas/Department'
designation:
type:
- string
- 'null'
max_biweekly_capacity:
type:
- number
- 'null'
example: 50.5
min_biweekly_capacity:
type: number
example: 20.5
max_weekly_capacity:
type:
- string
- 'null'
example: '24.5'
min_weekly_capacity:
type: string
example: '10'
max_daily_capacity:
type:
- string
- 'null'
example: 10
min_daily_capacity:
type: string
example: 0
default_availability:
type: string
example: available
username:
type: string
skills:
type: array
description: List of skills associated to an employee
items:
$ref: '#/components/schemas/Skill'
ssn_sin:
type:
- string
- 'null'
description: Social security number or Social insurance number of the employee
example: 123456789
contacts:
type: array
description: Employee contacts
items:
$ref: '#/components/schemas/EmployeeContact'
language:
type: string
example: en
payroll_number:
type: string
example: A123
seniority:
type: string
example: 897563
employment_type:
$ref: '#/components/schemas/EmploymentType'
cost_centre:
$ref: '#/components/schemas/CostCentre'
timezone:
description: 'Timezone name in IANA format (iana.org/time-zones). If not set, returns the branch timezone.
'
type: string
example: America/Toronto
required:
- id
- ac_id
- external_id
- demographics
- branch_id
- status
- contacts
Skill:
description: A skill or qualification associated to an employee
type: object
properties:
id:
type: integer
example: 1234
name:
type: string
example: Hoyer lift
PaginatedList:
description: Base model of all paginated lists
type: object
properties:
count:
type: integer
description: Number of items in the response
example: 1
page:
type: integer
description: Current page number
example: 1
total_pages:
type: integer
description: Total number of pages availbale
example: 1
required:
- count
- page
- total_pages
- items
EmployeeContactDemographics:
description: 'Collection of key/value pairs where keys are existing attributes in the employee contact profile, defined through the AlayaCare web application.
On the example below default profile keys for the employeecontact are used.
Example profile attributes:
+ `first_name`: string
+ `last_name`: string
+ `city`: string
+ `title`: string
+ `state`: string
+ `gender`: string
+ `relationship`: string
+ `contact_type`: string
+ `fax`: string
+ `company`: string
+ `phone_other`: string
+ `phone_main`: string
+ `address`: string
+ `country`: string
+ `zip`: string
+ `address_suite`: string
+ `remarks`: string
'
type: object
properties:
first_name:
description: Employee first name
type: string
example: Jane
last_name:
description: Employee last name
type: string
example: Smith
Role:
description: AlayaCare role
type: object
properties:
id:
type: integer
description: ID of the role
example: 1
name:
type: string
description: Name of the role
example: csc
description:
type: string
description: Name of the role in the web application
example: Coordinator
category:
type: string
description: Category of the role
example: admin
required:
- id
- name
EmployeeStatusCreate:
description: 'Enum of the status of an employee
'
type: string
enum:
- active
- pending
- on_hold
- suspended
- terminated
- applicant
- rejected
EmployeeCreate:
allOf:
- $ref: '#/components/schemas/EmployeeUpdate'
properties:
branch_id:
type: integer
description: 'Set employee branch. If not specified, will default to branch of the user creating the employee.
'
profile_id:
description: 'Use an existing client or contact profile ID when creating an employee.
Demographics will be shared between this employee and the previously
existing entity.
A unique username is still required for any new employee.
'
type: integer
example: 7890
status:
$ref: '#/components/schemas/EmployeeStatusCreate'
required:
- username
EmployeeStatusUpdate:
description: AlayaCare employee entity data for status update
type: object
properties:
status:
description: Updatable status of an employee
type: string
example: terminated
enum:
- active
- pending
- on_hold
- suspended
- terminated
- applicant
- rejected
comment:
description: Can only be set for employee termination
type: string
example: Employee is moving to another agency
required:
- status
EmployeeContact:
type: object
properties:
id:
type: integer
description: Employee contact ID
example: 1
ac_id:
type: string
description: AlayaCare ID for display in-app
example: AC000000024
external_id:
type:
- string
- 'null'
example: crm_employee_contact_external_id_1
description: Employee contact external ID
status:
description: Status of a contact
type: string
enum:
- enabled
- disabled
contact_type:
type:
- string
- 'null'
example: Medical
relationship:
type:
- string
- 'null'
example: Doctor
language:
type: string
example: en
demographics:
$ref: '#/components/schemas/EmployeeContactDemographics'
required:
- id
- ac_id
- external_id
- status
- demographics
parameters:
page:
description: Filter by page number.
name: page
in: query
required: false
schema:
type: integer
default: 1
ttl:
description: 'Pre-authorized URL time to live in seconds. `(default: 86400)`'
name: ttl
in: query
required: false
schema:
type: integer
default: 86400
status:
description: Filter by employee status, one or more using **OR**
name: status
in: query
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- active
- terminated
- suspended
- on_hold
- pending
- applicant
- rejected
- unknown
branch:
description: Filter by branch ID
name: branch
in: query
required: false
schema:
type: integer
count:
description: Number of items per page.
name: count
in: query
required: false
schema:
type: integer
default: 100
responses:
SuccessResponseEmployeeUpdate:
description: Employee updated successfuly
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
id: 1001
external_id: sor_employee_external_id_1
ErrorResponseEmployeeNotFound:
description: Employee not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 404
message: Employee not found.
SuccessResponseEmployeeCreate:
description: Employee created successfuly
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
id: 1001
external_id: sor_employee_external_id_1
ErrorResponseAuthentication:
description: Authorization required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 401
message: Authorization required.
securitySchemes:
basic_auth:
type: http
scheme: basic
description: Basic HTTP auth over https