Partner integration API to create organizations and caregivers, provide Single Sign-On into CareAcademy, and query course-completion and compliance data. OpenAPI 3.0, HTTP Basic auth.
openapi: 3.0.0
info:
version: 1.0.10
title: CareAcademy API
description: >-
The CareAcademy API allows integration partners to create seamless flows between their products and CareAcademy systems. As an integration partner, you can: <br />
<ol>
<li>Enable your users to use CareAcademy's system without requiring them to manage caregiver and organization information in both systems</li>
<li>Provide SSO to CareAcademy from your product</li>
<li>Query CareAcademy for an organization's course completion and compliance information</li>
<li>Provide access to an organization's compliance report from your product</li>
</ol>
<br />
<strong>Example scenarios</strong><br />
1) Allow your customers to signup for a CareAcademy free trial directly from your product's user interface. Your customer's organization and caregiver information can be passed to CareAcademy when the customer chooses to start the free trial from within your product's interface. Your customer can start a free trial seamlessly from your product's user interface without having to enter any organization or caregiver information. <br />
<br />
2) Allow your customers who already have a CareAcademy account to sign in to CareAcademy from your product's user interface. Your customer's organization and caregiver details can be pushed into CareAcademy allowing your customer move seamlessly into CareAcademy's systems without having to manage separate accounts. <br />
<br />
3) Display CareAcademy course completion and compliance data in your product. CareAcademy can provide you with granular data around a practitioner’s historical record of course completions including exam percentages and course specific compliance information. <br />
<br />
4) Provide your customers with a downloadable CareAcademy compliance report that includes all of the CareAcademy compliance related course data for an organization. <br />
<br />
<br />
<strong>Typical Integration Flow</strong><br />
Your customers will need to indicate if they have a CareAcademy account. Typically, CareAcademy integration partners prompt their users with a simple yes/no question asking if the customer already has an account with CareAcademy. <br />
<br />
<u>Your customer is new to CareAcademy</u><br />
If your customer indicates that they do not have a CareAcademy account then your system would make a POST request to the /organizations endpoint. This request creates a CareAcademy free trial, and the response will include a temporary url that you can redirect your customer to in order to log them into CareAcademy. Your customer will then be in a position to try CareAcademy. In this scenario, CareAcademy integration partners are expected to send the customer's caregiver information to CareAcademy so that the caregivers in your product are available in CareAcademy's system. This can be achieved by performing POST requests to the /practitioners endpoint. <br />
<br />
Often, CareAcademy integration partner customers have organizations with multiple locations. If this is the case then we highly recommend that your system sends these locations to CareAcademy by making a POST request to /locations after the POST or PUT to /organizations is complete. A locationId can then be provided when making POST requests to /practitioners in order to create caregivers in CareAcademy's system. If your customer does not have multiple locations in their organization then the locationId can be omitted from the POST to /practitioners.
<br />
<br />
<u>Your customer has a CareAcademy Account</u><br />
If your customer indicates that they already have an account at CareAcademy then your system is expected to make a PUT request to the /organizations endpoint. This will trigger a manual process at CareAcademy to enable the integration on the customer's existing account. In this scenario you will not be able to make further requests against the customer's CareAcademy account until the account's integration is configured by CareAcademy staff. This is a manual process - typically, the user is notified via your UI that CareAcademy will reach out to them to complete the integration.<br />
<br />
<br />
<i>A note regarding "integration ID's" </i><br />
The term <i>integration ID</i> appears in several endpoint descriptions and parameters. CareAcademy uses the term "integration ID" to represent an entity's unique ID in an integration partner's system. These ID's are expected to be unique within the integration context. <br />
<br />
For example, in order to create a caregiver in CareAcademy's system - a POST request can be made to the /practitioners endpoint. This endpoint requires an <i>integrationId</i> parameter. This value is typically the primary key value of the caregiver in the CareAcademy integration partner's system. Upon successfully creating a caregiver in the CareAcademy system, that caregiver could be signed in to CareAcademy by directing the caregiver to the url returned by the sign_in_url endpoint. The sign_in_url endpoint requires a <i>userIntegrationId</i> value. This value is expected to be the integrationId value provided with the POST request to the /practitioner endpoint.
security:
- BasicAuth: []
paths:
'/organizations/{organizationIntegrationId}':
post:
summary: >-
Create an organization.
parameters:
- in: path
name: organizationIntegrationId
required: true
description: >-
The external system's organization ID. For example, if you have
multiple agencies in your system, you can provide any unique
identifier for your agency.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- organizationName
- organizationState
- adminFirstName
- adminLastName
- adminEmail
- adminIntegrationId
allOf:
- $ref: '#/components/schemas/OrganizationsRequest'
properties:
locationId:
type: string
description: The ID of the location. If the organization has a single location then a value for locationId is expected to be provided. If an organization is multi location then the locationId value can be omitted, and locations can be added by performing a POST to /locations.
responses:
'200':
description: >-
The CareAcademy organization already exists. The organization was
updated with the provided integration ID.
content:
'*/*':
schema:
type: object
properties:
adminIntegrationId:
type: string
description: The integration ID for the admin user.
signInUrl:
type: string
description: >-
A temporary url that a browser can be directed to in order
to sign in a user to their CareAcademy dashboard.
additionalInformation:
type: array
items:
type: string
description: >-
Additional information about the result of the operation.
enum:
- admin created for existing agency
- no additional information
'201':
description: The organization was successfully created within CareAcademy
content:
'*/*':
schema:
type: object
properties:
adminIntegrationId:
type: string
description: The integration ID for the admin user.
signInUrl:
type: string
description: >-
A temporary url that a browser can be directed to in order
to sign in a user to their CareAcademy dashboard.
'202':
$ref: '#/components/responses/OrganizationsAccepted'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
put:
summary: >-
Flags an existing organization for review in order to associate the organization with a set of locations.
parameters:
- in: path
name: organizationIntegrationId
required: true
schema:
type: string
description: The integration ID for the organization.
requestBody:
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/OrganizationsRequest'
responses:
'202':
$ref: '#/components/responses/OrganizationsAccepted'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
'/locations/{organizationIntegrationId}':
post:
summary: >-
Creates an association between an organization and one or more locations. If a location does not exist then it will be created.
parameters:
- in: path
name: organizationIntegrationId
required: true
schema:
type: string
description: The integration ID for the organization. This is the same value passed as the organizationIntegrationId parameter to the Organizations POST API endpoint.
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Location'
- $ref: '#/components/schemas/LocationArray'
examples:
singleLocation:
summary: A single location
value:
{ resourceType: "Location", id: 'location-xyz', name: 'Location XYZ' }
multipleLocation:
summary: Multiple locations
value:
[{ resourceType: "Location", id: 'location-abc', name: 'Location ABC' }, { resourceType: "Location", id: 'location-xyz', name: 'Location XYZ' }]
description: The information required to create a location.
responses:
'200':
$ref: '#/components/responses/LocationCreateOrUpdateSuccess'
'201':
$ref: '#/components/responses/LocationCreateOrUpdatePartialSuccess'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
/sign_in_url:
get:
summary: >-
Retrieve a sign in url for a given user for Single Sign On. Either userIntegrationId or email is required. User integration ID is preferred.
parameters:
- in: query
name: userIntegrationId
description: >-
The external system's user ID. This is typically the ID of the
user's record in the system making a call to the CareAcademy API.
schema:
type: string
- in: query
name: email
description: The email address of the user being signed in.
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
type: object
properties:
signInUrl:
type: string
description: >-
A temporary url that a browser can be directed to in order
to sign in a user to their CareAcademy dashboard.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
description: Forbidden. The requested user is not allowed to sign in through SSO.
'404':
description: User not found.
'/compliance_report/{organizationIntegrationId}':
get:
summary: >-
Returns a copy of the compliance report.
parameters:
- in: path
name: organizationIntegrationId
required: true
description: >-
The integration ID for the organization. This is the same value passed as the organizationIntegrationId parameter to the Organizations POST API endpoint.
schema:
type: string
- in: query
name: filter[startDate]
required: true
description: >-
The starting date of the report you wish to pull. If a date is passed and is unrecognized as a valid date it will return an 'invalid date' error. Date should be in ISO 8601 format.
schema:
type: string
- in: query
name: filter[locationId]
required: true
description: >-
The location ID of the location to retreive data for.
schema:
type: string
- in: query
name: filter[endDate]
required: false
description: >-
The ending date of the report you wish to pull. If a date is passed and is unrecognized as a valid date it will return an 'invalid date' error. Date should be in ISO 8601 format. If no value is passed then the report end date defaults to the current time.
schema:
type: string
- in: query
name: filter[completeIncomplete]
required: false
description: >-
Specifies whether you wish to see a report of all completed courses, or courses that are not yet completed. The default for this parameter is “complete”. If a value of “incomplete” is passed, it will return the courses that are incomplete.
schema:
type: string
- in: query
name: page[after]
required: false
description: >-
Specifies the zero based index of the page of data that you would like to retrieve. For example, if you would like the second page of data then you would provide page[after]=1, or you would provide page[after]=2 in order to retrieve the third page of data. The response will include the first page of data when no page[after] value is provided. Note: the json response includes a "links" key which will contain a relative url that you can use to retrieve the next page of data. The "links" key is only included in the response when there are multiple pages of data
schema:
type: string
- in: header
name: Accept
required: false
description: >-
Specifies how you would like the data returned. Allowed values are "text/csv" and "application/json".
schema:
type: string
responses:
'200':
description: OK
content:
text/csv:
schema:
type: string
example: "Agency Name,First Name,Last Name,Integration ID,Title,Hire Date,Has State Registration,HCA Registration Date,HCA Registration ID,Birth Date,License Number,Employee ID,Total Duration (hours),Course Name,Course Completion Date,Course Description,Outline,State Approvals,Course Organization,Course Instructor,Course Location,Course Duration (hours),Is Initial,Is Annual,Exam Result,Course Duration (minutes)"
application/json:
schema:
type: object
example: {
data:
[
{
agencyName: "agency 1",
birthday: "2/15/57",
completedDate: "2022-10-31T00:00:00Z",
courseName: "Clients' Rights, HIPAA & Elder Abuse Prevention",
description: "In this CareAcademy class, we discuss clients' confidentiality, privacy, and related rights. We also discuss elder abuse and neglect, including how to prevent it and how to report it if it does occur.",
durationInMinutes: 60,
examResultPercentage: 95,
firstName: "Harry",
hcaRegDate: "2021-10-31T00:00:00Z",
hcaRegId: "abcdef",
hireDate: "2020-10-31T00:00:00Z",
instructor: "Samantha Jones",
integrationId: "abc-def",
isAnnual: false,
isInitial: true,
lastName: "Jones",
title: "Home Care Aide",
licenseNumber: "123456",
location: "www.careacademy.com",
organization: "CareAcademy.com | 1.866.227.3895 | hello@careacademy.com",
outline: "Course outline information",
}
],
links: {
next: {
href: "/api/v1/compliance_report/organizationID?page[after]=1"
}
}
}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: An organization could not be found for the given organizationIntegrationId.
/practitioners:
post:
summary: Creates a practitioner. If a practitioner already exists within CareAcademy but has not been linked yet to the integration, this will do so by setting integrationId for the first time with this call.
responses:
'201':
#$ref: '#/components/responses/PractitionerCreateOrUpdateSuccessResponse'
description: The operation was successful.
content:
'*/*':
schema:
type: string
properties:
additionalInformation:
description: Information and warnings regarding any problems with the request. For general warnings, the parameterName value will be "_".
type: array
items:
type: object
properties:
parameterName:
type: string
description:
type: string
dashboardName:
type: string
description: The name of the dashboard that the practitioner will appear under.
practitioner:
type: object
allOf:
- $ref: '#/components/schemas/PractitionerResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PractitionerWithRequiredFields'
properties:
isInitialTrainingRequired:
type: boolean
description: >-
If true, the practitioner will be auto-enrolled into initial
bundle (this is the default behavior). If false, the
practitioner will not be auto-enrolled into the initial
training bundle.
Note that this value can only be set if the practitioner is being added into CareAcademy for the first time (i.e it cannot be updated).
isAnnualTrainingOverdue:
type: boolean
description: >-
This value is only used if the practitioner does not need
initial training (see the isInitialTrainingRequired
parameter). If this value is set to true then the
practitioner will be enrolled in annual trainig which is due
date immediately. If this value is false then the annual
training due date will be in the future as per enrollment
schedule in CareAcademy (this is the default behavior).
Note that this value can only be set if the practitioner is being added into CareAcademy for the first time (i.e it cannot be updated).
description: The information required to create a practitioner.
'/practitioners/{integrationId}':
put:
summary: Updates a practitioner.
parameters:
- in: path
name: integrationId
required: true
description: The practitioner's integration ID.
schema:
type: string
responses:
'200':
$ref: '#/components/responses/PractitionerCreateOrUpdateSuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Practictioner not found.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Practitioner'
description: >-
The practitioner information to update. Only supply the values that
should be updated.
servers:
- url: 'https://staging.careacademy.com/api/v1'
components:
schemas:
OrganizationsRequest:
type: object
required:
- organizationName
- organizationState
- adminFirstName
- adminLastName
- adminEmail
- adminIntegrationId
properties:
organizationName:
type: string
description: The organization's name.
organizationState:
type: string
description: >-
The organization's US state or Canadian province. This can
be the state/province name or abbreviation.
adminFirstName:
type: string
description: The organization administrator's first name.
adminLastName:
type: string
description: The organization administrator's last name.
adminEmail:
type: string
description: The organization administrator's email address.
adminPhone:
type: string
description: The organization administrator's phone number.
adminIntegrationId:
type: string
description: >-
The organization administrator's integration ID. This is
typically the ID of the administrator's record in the system
making a call to the CareAcademy API. This ID can be used in
subsequent calls to the CareAcademy API.
Location:
type: object
properties:
id:
type: string
name:
type: string
resourceType:
type: string
enum:
- Location
LocationArray:
properties:
locations:
type: array
items:
type: object
allOf:
- $ref: '#/components/schemas/Location'
PractitionerWithRequiredFields:
required:
- integrationId
- name
- telecom
- email
- hireDate
- organizationIntegrationId
allOf:
- $ref: '#/components/schemas/Practitioner'
properties:
state:
type: string
description: Providing a state will allow CareAcademy to assign this practitioner to a location in the state specified when locationId is omitted.
Practitioner:
type: object
properties:
active:
type: boolean
description: Indicates if the practitioner is active or not. The default value is true.
name:
$ref: '#/components/schemas/HumanName'
telecom:
$ref: '#/components/schemas/ContactPoint'
birthDate:
type: string
format: date
description: >-
This parameter is required if the organization's state
requires the birthday to be used to calculate due dates and
report to auditors. The value should follow the format
defined by full-date in RFC3339
(https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14)
integrationId:
type: string
description: >-
ID that will be used to reference the practitioner by the API consumer, such as when using the PUT practitioner end point. This ID must be unique.
hireDate:
type: string
format: date
description: >-
Hire date used in calculating compliance due dates and in
generating training logs. This value should follow the
format defined by full-date in RFC3339
(https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14)
organizationIntegrationId:
type: string
description: >-
Unique identifier of the organization that the practitioner
needs to be added to
locationId:
type: string
description: The ID of the location for this practitioner
licenseNumber:
type: string
description: >-
If you need to have the license number of the practitioner
to appear in auditing logs (for example a CNA / HHA license
number)
studentType:
type: string
description: >-
This can be useful in order to track compliance better and
also add the practitioner in the right curriculum track.
enum:
- home care aide
- home health aide
- certified nursing assistant
- registered nurse
- administrator
registrationId:
type: string
description: >-
In states that have registries, this may be required for
auditing purposes. In California, for example, it represents the HCA registration ID, which must be a 10 numerical digit string. Otherwise, it will be rejected by our system.
registrationDate:
type: string
format: date
description: >-
In states that have registries, this date may be required
for auditing purposes. The value should follow the format
defined by full-date in RFC3339
(https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14)
PractitionerResponse:
type: object
properties:
practitionerIntegrationId:
type: string
description: The unique identifier for the practitioner.
status:
type: string
description: The status of the practitioner.
enum:
- active
- deleted
- deactivated
active:
type: boolean
firstName:
type: string
lastName:
type: string
phone:
type: string
email:
type: string
birthDate:
type: string
format: date
hireDate:
type: string
format: date
isInitialTrainingRequired:
type: boolean
isAnnualTrainingOverdue:
type: boolean
licenseNumber:
type: string
studentType:
type: string
registrationId:
type: string
registrationDate:
type: string
format: date
ContactPoint:
description: 'The mobile phone number and email address of the practitioner. Further documentation here: https://www.hl7.org/fhir/datatypes.html#ContactPoint'
type: object
required:
- system
- value
properties:
system:
description: The type of contact point. Use "phone" for mobile phone and "email" for email address. All other system types are ignored.
type: string
enum: [email, phone]
value:
description: The value, for example if the system is "email" then the value would be the email address of the practitioner.
type: string
example:
- system: email
value: jane@careacademy.com
- system: phone
value: 555-555-1234
HumanName:
description: 'The name of the practitioner. Further documentation here: https://www.hl7.org/fhir/datatypes.html#humanname'
type: object
required:
- use
- family
- given
properties:
text:
type: string
description: The full name of the practitioner
use:
type: string
description: The only supported value is "official" - other uses will be ignored.
family:
type: string
description: The family name - often called "surname" or "last name"
given:
type: array
description: Given names. This can include middle name. Often, this will be a single value which is the practictioner's first name.
items:
type: string
example:
- text: Jane Smith
use: official
family: Smith
given: [Jane]
LocationCreateOrUpdateResponse:
type: object
properties:
additionalInformation:
description: Information and warnings regarding any problems with the request. For general warnings, the parameterName value will be "_".
type: array
items:
type: object
properties:
parameterName:
type: string
description:
type: string
locations:
type: array
items:
type: object
allOf:
- $ref: '#/components/schemas/Location'
responses:
LocationCreateOrUpdateSuccess:
description: The operation was successful.
content:
'*/*':
schema:
type: object
allOf:
- $ref: '#/components/schemas/LocationCreateOrUpdateResponse'
LocationCreateOrUpdatePartialSuccess:
description: The operation was partially successful. One or more loations could not be created. See the additionalInformation response property for more information.
content:
'*/*':
schema:
type: object
allOf:
- $ref: '#/components/schemas/LocationCreateOrUpdateResponse'
PractitionerCreateOrUpdateSuccessResponse:
description: The operation was successful.
content:
'*/*':
schema:
type: object
properties:
additionalInformation:
description: Information and warnings regarding any problems with the request. For general warnings, the parameterName value will be "_".
type: array
items:
type: object
properties:
parameterName:
type: string
description:
type: string
practitioner:
type: object
allOf:
- $ref: '#/components/schemas/PractitionerResponse'
OrganizationsAccepted:
description: >-
The request has been queued for manual processing. This response is
issued when the provided information needs to be manually verified
by CareAcademy staff because the provided organization and admin
information is not sufficient to link an account with an existing
CareAcademy organization.
Forbidden:
description: >-
The identity associated with the API credentials for this request is not
allowed to perform the requested operation.
UnauthorizedError:
description: Authentication information is missing or invalid
BadRequest:
description: Bad Request. One or more required parameters are missing or invalid.
content:
'*/*':
schema:
type
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/careacademy/refs/heads/main/openapi/careacademy-openapi-original.yml