openapi: 3.0.0
info:
  version: 1.0.10
  title: CareAcademy Compliance Report Organizations 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.'
servers:
- url: https://staging.careacademy.com/api/v1
security:
- BasicAuth: []
tags:
- name: Organizations
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'
      tags:
      - Organizations
    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'
      tags:
      - Organizations
components:
  responses:
    BadRequest:
      description: Bad Request. One or more required parameters are missing or invalid.
      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
              errors:
                description: An array of field errors. For general errors, the parameterName value will be "_".
                type: array
                items:
                  type: object
                  properties:
                    parameterName:
                      type: string
                    errorDescription:
                      type: string
    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.
    UnauthorizedError:
      description: Authentication information is missing or invalid
  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.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic