API docs by Redocly

MedTrainer Public API (1.0.0)

The MedTrainer Public API allows external integrations to search and manage core directory resources such as locations, divisions, and practitioners.

This specification describes the available endpoints, request parameters, payloads, authentication requirements, and expected responses for clients integrating with the platform.

Most resource endpoints return FHIR-aligned JSON with content type application/fhir+json. Protected endpoints accept authentication through either the X-API-Key header or Authorization: Bearer <token>.

Getting started

This guide walks you through how to generate an API Key from the platform. This key will allow you to authenticate and interact with the available APIs.

Prerequisites

Before you begin, make sure you have:

A valid account and access to the platform

Proper permissions to generate an API Key (Super Admin)

Logged into the platform

Step-by-step

1. Log in to the platform

Sign in to the MedTrainer platform using your credentials.

2. Open Organization settings

Once you're in:

On the left-side menu

Click on Organization

3. Expand “Organization Management” and find the “API keys manager”

Inside Organization Settings:

Expand “Organization Management” menu

Here you’ll find all options to configure the organization

Look for “API keys manager” option and click on it

4. Create a new API Key group

In the “API keys manager” page:

Click on “Create API key group”

Fill the following fields:

name

description

Confirm the action by clicking the “Create” button.

5. Activate the API Key “Default”

After generating the API key group:

On the “API Keys Manager” page, you will see the newly created API key group, along with a “Default” API key in an “Inactive” status.

To activate the “Default” API key:

Click on the status to expand the available options.

Once the list is expanded, select the “Active” status

This API key is required and must be available to use the MedTrainer Public APIs
Important: Treat your API Key like a password. Keep it private and secure.

Locations

Public location lookup and mutation endpoints

Search locations

Returns a FHIR Bundle with location resources.

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_count
integer >= 1
Default: 20

Number of resources to return. Must be a positive integer.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,name

Comma-separated field selector.

For location, division, position, department, and practitioner category searches, the implemented selectors are id, name, division, locations, and clinical as applicable. The default when _elements is omitted: locations default to id,name; divisions default to id,name,locations; positions default to id,name,clinical; departments default to id,name; practitioner categories default to id,name.

For practitioners, nested selectors are allowed, including values such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber. The public practitioner response uses extension.user.status and extension.user.statusReason for the visible status state; the legacy employeeCategoryId is not exposed. When _elements is omitted on practitioner search or get-by-id, the full public resource is returned.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Documentation examples use relative pagination paths so they work across local, staging, and production environments.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 3,
  • "link": [
    ],
  • "entry": [
    ]
}

Create a location

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Required location name. Cannot be blank or whitespace-only.

state
required
string non-empty ^\S+.*$

Required state value. Cannot be blank or whitespace-only.

addressLine
string

Location address line.

city
string

Location city. If provided, it cannot be blank or whitespace-only.

zipCode
string

Location ZIP or postal code.

phoneNumber
string <= 10 characters ^[0-9]+$

Location phone number. Must contain only digits up to 10 characters.

fax
string <= 10 characters ^[0-9]+$

Location fax number. Must contain only digits up to 10 characters.

email
string <email>

Location email address.

sendEmail
boolean
Default: false

Whether to send email for this location.

enabledCredentialing
boolean
Default: false

Whether credentialing is enabled for this location.

object

Optional division reference wrapper.

Responses

Request samples

Content type
application/json
{
  • "name": "North Campus",
  • "state": "State",
  • "city": "City",
  • "addressLine": "Address 1",
  • "zipCode": "33101",
  • "phoneNumber": "0987654321",
  • "fax": "1234567890",
  • "email": "first@test.com",
  • "sendEmail": false,
  • "enabledCredentialing": false,
  • "division": {
    }
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Get a location by public ID

Resolves the public location identifier before fetching the resource. When _elements is provided, only the requested fields are returned.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: LOC-001

Public location identifier.

query Parameters
_elements
string
Example: _elements=id,name

Comma-separated field selector.

For location, division, position, department, and practitioner category searches, the implemented selectors are id, name, division, locations, and clinical as applicable. The default when _elements is omitted: locations default to id,name; divisions default to id,name,locations; positions default to id,name,clinical; departments default to id,name; practitioner categories default to id,name.

For practitioners, nested selectors are allowed, including values such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber. The public practitioner response uses extension.user.status and extension.user.statusReason for the visible status state; the legacy employeeCategoryId is not exposed. When _elements is omitted on practitioner search or get-by-id, the full public resource is returned.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Documentation examples use relative pagination paths so they work across local, staging, and production environments.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Location",
  • "id": "LOC-001",
  • "name": "North Campus",
  • "addressLine": "Address 1",
  • "city": "City",
  • "state": "State",
  • "division": {
    },
  • "zipCode": "33101",
  • "phoneNumber": "0987654321",
  • "fax": "1234567890",
  • "email": "first@test.com",
  • "sendEmail": false,
  • "enabledCredentialing": true
}

Update a location

Resolves the public location identifier before updating the resource.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: LOC-001

Public location identifier.

Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Required location name. Cannot be blank or whitespace-only.

state
string non-empty ^\S+.*$

Optional state value. If provided, it cannot be null, blank, or whitespace-only. Omit the field completely if you do not wish to update this field.

addressLine
string

Location address line.

city
string

Location city. If provided, it cannot be blank or whitespace-only.

zipCode
string

Location ZIP or postal code.

phoneNumber
string <= 10 characters ^[0-9]+$

Location phone number. Must contain only digits up to 10 characters.

fax
string <= 10 characters ^[0-9]+$

Location fax number. Must contain only digits up to 10 characters.

email
string <email>

Location email address.

sendEmail
boolean
Default: false

Whether to send email for this location.

enabledCredentialing
boolean
Default: false

Whether credentialing is enabled for this location.

object

Optional division reference wrapper.

Responses

Request samples

Content type
application/json
{
  • "name": "North Campus",
  • "state": "State",
  • "city": "City",
  • "addressLine": "Address 1",
  • "zipCode": "33101",
  • "phoneNumber": "0987654321",
  • "fax": "1234567890",
  • "email": "first@test.com",
  • "sendEmail": false,
  • "enabledCredentialing": false,
  • "division": {
    }
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Update a location with PATCH

Resolves the public location identifier before updating the resource with the same request body and validation rules as PUT.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: LOC-001

Public location identifier.

Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Required location name. Cannot be blank or whitespace-only.

state
string non-empty ^\S+.*$

Optional state value. If provided, it cannot be null, blank, or whitespace-only. Omit the field completely if you do not wish to update this field.

addressLine
string

Location address line.

city
string

Location city. If provided, it cannot be blank or whitespace-only.

zipCode
string

Location ZIP or postal code.

phoneNumber
string <= 10 characters ^[0-9]+$

Location phone number. Must contain only digits up to 10 characters.

fax
string <= 10 characters ^[0-9]+$

Location fax number. Must contain only digits up to 10 characters.

email
string <email>

Location email address.

sendEmail
boolean
Default: false

Whether to send email for this location.

enabledCredentialing
boolean
Default: false

Whether credentialing is enabled for this location.

object

Optional division reference wrapper.

Responses

Request samples

Content type
application/json
{
  • "name": "North Campus",
  • "state": "State",
  • "city": "City",
  • "addressLine": "Address 1",
  • "zipCode": "33101",
  • "phoneNumber": "0987654321",
  • "fax": "1234567890",
  • "email": "first@test.com",
  • "sendEmail": false,
  • "enabledCredentialing": false,
  • "division": {
    }
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Divisions

Public division lookup and mutation endpoints

Search divisions

Returns a FHIR Bundle with division resources.

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_count
integer >= 1
Default: 20

Number of resources to return. Must be a positive integer.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,name

Comma-separated field selector.

For location, division, position, department, and practitioner category searches, the implemented selectors are id, name, division, locations, and clinical as applicable. The default when _elements is omitted: locations default to id,name; divisions default to id,name,locations; positions default to id,name,clinical; departments default to id,name; practitioner categories default to id,name.

For practitioners, nested selectors are allowed, including values such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber. The public practitioner response uses extension.user.status and extension.user.statusReason for the visible status state; the legacy employeeCategoryId is not exposed. When _elements is omitted on practitioner search or get-by-id, the full public resource is returned.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Documentation examples use relative pagination paths so they work across local, staging, and production environments.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 3,
  • "link": [
    ],
  • "entry": [
    ]
}

Create a division

Creates a division with a non-blank name and at least one linked location ID.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Required division name. Cannot be blank or whitespace-only.

locations
required
Array of strings non-empty [ items non-empty ]

Required list of location IDs. At least one value must be provided, and each value cannot be blank or whitespace-only.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "North Division",
  • "locations": [
    ]
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Get a division by ID

Resolves the public division identifier before fetching the resource.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
divisionId
required
string
Example: DIV-001

Division identifier.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Division",
  • "id": "DIV-123",
  • "name": "Clinical Division",
  • "locations": [
    ]
}

Update a division

Accepts partial updates. Send at least one of name or locations. Resolves the public division identifier before updating the resource. A 422 response also covers duplicate division names, locations that do not exist or belong to another company, and locations that are assigned to another non-default division.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
divisionId
required
string
Example: DIV-001

Division identifier.

Request Body schema: application/json
required
Any of
name
required
string [ 1 .. 100 ] characters

Conditionally required division name. Send name or locations. If name is provided, it cannot be blank or whitespace-only.

locations
Array of strings[ items non-empty ]

Conditionally required list of location IDs. Send name or locations. Each provided value cannot be blank or whitespace-only. Send an empty array to remove all linked locations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Updated Division"
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Update a division with PATCH

Resolves the public division identifier before updating the resource with the same payload as PUT and is routed to the same update handler. It returns the same validation and downstream business-rule errors as PUT.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
divisionId
required
string
Example: DIV-001

Division identifier.

Request Body schema: application/json
required
Any of
name
required
string [ 1 .. 100 ] characters

Conditionally required division name. Send name or locations. If name is provided, it cannot be blank or whitespace-only.

locations
Array of strings[ items non-empty ]

Conditionally required list of location IDs. Send name or locations. Each provided value cannot be blank or whitespace-only. Send an empty array to remove all linked locations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Updated Division"
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Positions

Public position lookup endpoints

Search positions

Returns a FHIR Bundle with position resources.

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_count
integer >= 1
Default: 20

Number of resources to return. Must be a positive integer.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,name

Comma-separated field selector.

For location, division, position, department, and practitioner category searches, the implemented selectors are id, name, division, locations, and clinical as applicable. The default when _elements is omitted: locations default to id,name; divisions default to id,name,locations; positions default to id,name,clinical; departments default to id,name; practitioner categories default to id,name.

For practitioners, nested selectors are allowed, including values such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber. The public practitioner response uses extension.user.status and extension.user.statusReason for the visible status state; the legacy employeeCategoryId is not exposed. When _elements is omitted on practitioner search or get-by-id, the full public resource is returned.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Documentation examples use relative pagination paths so they work across local, staging, and production environments.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 3,
  • "link": [
    ],
  • "entry": [
    ]
}

Get a position by public ID

Resolves the public position identifier before fetching the resource.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: POS-001

Public position identifier.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Position",
  • "id": "POS-001",
  • "name": "Analyst",
  • "clinical": true
}

Departments

Public department lookup endpoints

Search departments

Returns a FHIR Bundle with department resources.

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_count
integer >= 1
Default: 20

Number of resources to return. Must be a positive integer.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,name

Comma-separated field selector.

For location, division, position, department, and practitioner category searches, the implemented selectors are id, name, division, locations, and clinical as applicable. The default when _elements is omitted: locations default to id,name; divisions default to id,name,locations; positions default to id,name,clinical; departments default to id,name; practitioner categories default to id,name.

For practitioners, nested selectors are allowed, including values such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber. The public practitioner response uses extension.user.status and extension.user.statusReason for the visible status state; the legacy employeeCategoryId is not exposed. When _elements is omitted on practitioner search or get-by-id, the full public resource is returned.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Documentation examples use relative pagination paths so they work across local, staging, and production environments.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 3,
  • "link": [
    ],
  • "entry": [
    ]
}

Get a department by public ID

Resolves the public department identifier before fetching the resource.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: DEPT-001

Public department identifier.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Department",
  • "id": "DEPT-001",
  • "name": "Compliance/HIPAA"
}

Practitioner Categories

Public practitioner category lookup endpoints

Search practitioner categories

Returns a FHIR Bundle with practitioner category resources.

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_count
integer >= 1
Default: 20

Number of resources to return. Must be a positive integer.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,name

Comma-separated field selector for practitioner category search.

The only implemented selectors for this endpoint are id and name. When _elements is omitted, practitioner category resources default to id,name.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 3,
  • "link": [
    ],
  • "entry": [
    ]
}

Get a practitioner category by public ID

Resolves the public practitioner category identifier before fetching the resource.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: PCAT-001

Public practitioner category identifier.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "PractitionerCategory",
  • "id": "PCAT-001",
  • "name": "Nursing"
}

Practitioners

Public practitioner lookup, search, and mutation endpoints

Create a practitioner

Creates a practitioner/provider profile for the authenticated company context.

A 422 response indicates either request-body validation failures, unresolved related public IDs such as extension.employment.positionId, extension.employment.departmentId, or extension.user.location, or a validation error returned by the upstream provider-profile API.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
resourceType
string^\s*Practitioner\s*$

Optional resource type discriminator. When present it must equal Practitioner.

required
object (PractitionerWriteName)

Practitioner name payload.

given and family are required. Any provided string must contain at least one non-whitespace character.

Every string field below is constrained to letters, numbers, spaces, apostrophes, periods, and hyphens. The character allowlist regex enforced server-side is ^[A-Za-z0-9 .'\-]+$. Length limits enforced by request validation: given/family 255, middle 100, other.given/other.middle/other.family 100, and other.suffix 20.

birthDate
string (MmDdYyyyDateString) ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-...

Date string in MM/DD/YYYY format.

The value must represent a real calendar date accepted by server-side validation, not just a string that matches the pattern. For example, 02/31/2026 is rejected.

gender
string [ 1 .. 100 ] characters ^[A-Za-z0-9 .'\-]+$

Only letters, numbers, spaces, apostrophes, periods, and hyphens are allowed. Maximum 100 characters.

required
object (PractitionerWriteTelecom)

Practitioner telecom payload.

email is required. Any provided string must contain at least one non-whitespace character.

object (PractitionerWriteHomeAddress)

Optional home address payload.

object (PractitionerWriteMailingAddress)

Optional mailing address payload.

The server enforces:

  • a character allowlist regex ^[A-Za-z0-9 .'\-]+$ on line[0], line[1], and city
  • maxLength: 100 on county and province
required
object (PractitionerWriteExtension)

Practitioner extension payload. employment and user are required.

Responses

Request samples

Content type
application/json
{
  • "resourceType": "Practitioner",
  • "name": {
    },
  • "birthDate": "01/01/1990",
  • "gender": "male",
  • "telecom": {
    },
  • "address": {
    },
  • "mailingAddress": {
    },
  • "extension": {
    }
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Search practitioners

Returns a FHIR Bundle of practitioner resources. _elements supports comma-separated selectors and may include nested paths such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber.

_elements values are normalized by trimming surrounding whitespace. Unknown selectors are preserved in pagination links but ignored when building each practitioner resource.

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_count
integer >= 1
Default: 20

Number of resources to return. Must be a positive integer.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,name

Comma-separated field selector.

For location, division, position, department, and practitioner category searches, the implemented selectors are id, name, division, locations, and clinical as applicable. The default when _elements is omitted: locations default to id,name; divisions default to id,name,locations; positions default to id,name,clinical; departments default to id,name; practitioner categories default to id,name.

For practitioners, nested selectors are allowed, including values such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber. The public practitioner response uses extension.user.status and extension.user.statusReason for the visible status state; the legacy employeeCategoryId is not exposed. When _elements is omitted on practitioner search or get-by-id, the full public resource is returned.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Documentation examples use relative pagination paths so they work across local, staging, and production environments.

Responses

Response samples

Content type
application/fhir+json
Example
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 3,
  • "link": [
    ],
  • "entry": [
    ]
}

Get a practitioner by public ID

Returns a single practitioner resource. If _elements is omitted, the full public practitioner resource is returned. _elements accepts the same nested selector syntax as practitioner search and trims surrounding whitespace before filtering.

A 404 response indicates the practitioner public ID could not be resolved. A 422 response indicates validation failed while reading or normalizing the upstream practitioner data.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: PRAC-001

Public practitioner identifier.

query Parameters
_elements
string
Example: _elements=id,name

Comma-separated field selector.

For location, division, position, department, and practitioner category searches, the implemented selectors are id, name, division, locations, and clinical as applicable. The default when _elements is omitted: locations default to id,name; divisions default to id,name,locations; positions default to id,name,clinical; departments default to id,name; practitioner categories default to id,name.

For practitioners, nested selectors are allowed, including values such as telecom.email, telecom.homePhone, address.city, extension.user.status, extension.user.statusReason, extension.user.userType, or extension.provider.npiNumber. The public practitioner response uses extension.user.status and extension.user.statusReason for the visible status state; the legacy employeeCategoryId is not exposed. When _elements is omitted on practitioner search or get-by-id, the full public resource is returned.

Whitespace around values is trimmed. Unknown selectors are preserved in pagination links but ignored when each resource is built.

Documentation examples use relative pagination paths so they work across local, staging, and production environments.

Responses

Response samples

Content type
application/fhir+json
Example
{
  • "resourceType": "Practitioner",
  • "name": {
    },
  • "telecom": {
    }
}

Update a practitioner

Updates a practitioner/provider profile identified by publicId.

The request body is a partial update: every top-level field is optional. Omitted fields retain their existing values. Any field that is present is validated with the same format/length/pattern rules as the create payload.

A 422 response indicates either request-body validation failures, unresolved related public IDs such as extension.employment.positionId, extension.employment.departmentId, or extension.user.location, or a validation error returned by the upstream provider-profile API.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: PRAC-001

Public practitioner identifier.

Request Body schema: application/json
required
resourceType
string^\s*Practitioner\s*$

Optional resource type discriminator. When present it must equal Practitioner.

object (PractitionerUpdateName)

Practitioner name payload for partial updates. All fields are optional — send only the fields you want to change.

Every string field below is constrained to letters, numbers, spaces, apostrophes, periods, and hyphens. The character allowlist regex enforced server-side is ^[A-Za-z0-9 .'\-]+$. Length limits enforced by request validation: given/family 255, middle 100, other.given/other.middle/other.family 100, and other.suffix 20.

birthDate
string (MmDdYyyyDateString) ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-...

Date string in MM/DD/YYYY format.

The value must represent a real calendar date accepted by server-side validation, not just a string that matches the pattern. For example, 02/31/2026 is rejected.

gender
string [ 1 .. 100 ] characters ^[A-Za-z0-9 .'\-]+$

Only letters, numbers, spaces, apostrophes, periods, and hyphens are allowed. Maximum 100 characters.

object (PractitionerUpdateTelecom)

Practitioner telecom payload for partial updates. All fields are optional — send only the fields you want to change. Any provided string must contain at least one non-whitespace character.

object (PractitionerWriteHomeAddress)

Optional home address payload.

object (PractitionerWriteMailingAddress)

Optional mailing address payload.

The server enforces:

  • a character allowlist regex ^[A-Za-z0-9 .'\-]+$ on line[0], line[1], and city
  • maxLength: 100 on county and province
object (PractitionerUpdateExtension)

Practitioner extension payload for partial updates. All nested objects and their fields are optional — send only the pieces you want to change.

The practitioner user status fields are nested under extension.user.

Responses

Request samples

Content type
application/json
{
  • "resourceType": "Practitioner",
  • "name": {
    },
  • "birthDate": "01/01/1990",
  • "gender": "male",
  • "telecom": {
    },
  • "address": {
    },
  • "mailingAddress": {
    },
  • "extension": {
    }
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Update a practitioner with PATCH

Accepts the same payload as PUT and is routed to the same update handler. Both verbs behave as partial updates: send only the fields you want to change.

A 422 response indicates either request-body validation failures, unresolved related public IDs such as extension.employment.positionId, extension.employment.departmentId, or extension.user.location, or a validation error returned by the upstream provider-profile API.

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: PRAC-001

Public practitioner identifier.

Request Body schema: application/json
required
resourceType
string^\s*Practitioner\s*$

Optional resource type discriminator. When present it must equal Practitioner.

object (PractitionerUpdateName)

Practitioner name payload for partial updates. All fields are optional — send only the fields you want to change.

Every string field below is constrained to letters, numbers, spaces, apostrophes, periods, and hyphens. The character allowlist regex enforced server-side is ^[A-Za-z0-9 .'\-]+$. Length limits enforced by request validation: given/family 255, middle 100, other.given/other.middle/other.family 100, and other.suffix 20.

birthDate
string (MmDdYyyyDateString) ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-...

Date string in MM/DD/YYYY format.

The value must represent a real calendar date accepted by server-side validation, not just a string that matches the pattern. For example, 02/31/2026 is rejected.

gender
string [ 1 .. 100 ] characters ^[A-Za-z0-9 .'\-]+$

Only letters, numbers, spaces, apostrophes, periods, and hyphens are allowed. Maximum 100 characters.

object (PractitionerUpdateTelecom)

Practitioner telecom payload for partial updates. All fields are optional — send only the fields you want to change. Any provided string must contain at least one non-whitespace character.

object (PractitionerWriteHomeAddress)

Optional home address payload.

object (PractitionerWriteMailingAddress)

Optional mailing address payload.

The server enforces:

  • a character allowlist regex ^[A-Za-z0-9 .'\-]+$ on line[0], line[1], and city
  • maxLength: 100 on county and province
object (PractitionerUpdateExtension)

Practitioner extension payload for partial updates. All nested objects and their fields are optional — send only the pieces you want to change.

The practitioner user status fields are nested under extension.user.

Responses

Request samples

Content type
application/json
{
  • "resourceType": "Practitioner",
  • "name": {
    },
  • "birthDate": "01/01/1990",
  • "gender": "male",
  • "telecom": {
    },
  • "address": {
    },
  • "mailingAddress": {
    },
  • "extension": {
    }
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Learning Courses

Company course catalog endpoints

Search the company course catalog

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_count
integer [ 1 .. 200 ]
Default: 20

Number of courses or assignments to return. Must be between 1 and 200.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,title,description

Comma-separated ActivityDefinition selectors. Supported selectors include id, title, description, purpose, date, effectivePeriod, effectivePeriod.end, extension, extension.duration, extension.chapters, or extension.certificateApprovals. id and resourceType are always returned. Unknown selectors are ignored.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 1,
  • "link": [
    ],
  • "entry": [
    ]
}

Retrieve a course from the company catalog

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
publicId
required
string
Example: CRS-01HZX5V9X8YQ
query Parameters
_elements
string
Example: _elements=id,title,extension

Comma-separated ActivityDefinition selectors. The same selectors supported by course search are accepted. id and resourceType are always returned. Unknown selectors are ignored.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "ActivityDefinition",
  • "id": "CRS-01HZX5V9X8YQ",
  • "title": "Infection Prevention",
  • "description": "Infection prevention fundamentals",
  • "purpose": "Reduce preventable infections",
  • "date": "09/01/2026",
  • "effectivePeriod": {
    },
  • "extension": [
    ]
}

Learning Course Assignments

Company course-assignment creation, search, and deletion endpoints

Create course assignments

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
resourceType
required
string
Value: "Task"
idCourse
required
string non-empty .*\\S.*

Course public ID from the authenticated company catalog.

idEmployee
required
Array of strings non-empty unique [ items non-empty .*\\S.* ]

One or more employee public IDs from the authenticated company.

assignmentDate
required
string (MmDdYyyyDateString) ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-...

Assignment date. Date ordering and minimum-date rules are enforced by the downstream assignment service.

dueDate
required
string (MmDdYyyyDateString) ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-...

Due date. Must be equal to or later than assignmentDate when accepted by the downstream service.

expirationDate
required
string (MmDdYyyyDateString) ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-...

Expiration date. Must be equal to or later than dueDate when accepted by the downstream service.

assignmentBy
string non-empty .*\\S.*

Optional employee public ID. If omitted, the API-key owner's employee is used.

idManager
string non-empty .*\\S.*

Optional manager employee public ID in the API-key company.

note
string <= 500 characters

Optional note, limited to 500 characters.

object

Optional recurrence and notification settings. If supplied, recurrence is required. If extension is omitted, recurrence defaults to Does not recur and sendMail defaults to false. Recurrence is rejected for ProTraining courses, and hire-date recurrence requires a hire date for every target employee.

Responses

Request samples

Content type
application/json
{
  • "resourceType": "Task",
  • "idCourse": "CRS-01HZX5V9X8YQ",
  • "idEmployee": [
    ],
  • "assignmentDate": "09/25/2026",
  • "dueDate": "10/25/2026",
  • "expirationDate": "10/01/2027",
  • "assignmentBy": "EMP-ADMIN",
  • "idManager": "EMP-MANAGER",
  • "note": "Complete this recurring assignment before the expiration date.",
  • "extension": {
    }
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}

Search course assignments for an employee

Authorizations:
ApiKeyHeaderBearerAuth
query Parameters
_practitionerId
required
string non-empty
Example: _practitionerId=EMP-001

Public employee identifier whose assignments are returned.

_count
integer [ 1 .. 200 ]
Default: 20

Number of courses or assignments to return. Must be between 1 and 200.

_page
integer >= 1
Default: 1

1-based page number. Must be a positive integer.

_elements
string
Example: _elements=id,practitionerId,idCourse,dueStatus

Comma-separated assignment field selector. Supported values are id, practitionerId, practitionerName, idCourse, courseTitle, assignmentStatus, assignmentDate, assignedBy, dueDate, dueStatus, percentageProgress, and completionDate.

resourceType and id are always returned. Whitespace is trimmed and unknown selectors are ignored in resources but preserved in pagination links.

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Bundle",
  • "type": "searchset",
  • "total": 1,
  • "link": [
    ],
  • "entry": [
    ]
}

Remove a course assignment

Authorizations:
ApiKeyHeaderBearerAuth
path Parameters
assignmentPublicId
required
string
Example: ASN-01HZX5V9X8YQ
Request Body schema: application/json
optional

Optional deletion settings. If omitted, sendMail defaults to false. If supplied, the extension must contain exactly one object with a boolean sendMail field.

resourceType
required
string
Value: "Task"
required
Array of objects = 1 items

Responses

Request samples

Content type
application/json
{
  • "resourceType": "Task",
  • "extension": [
    ]
}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "OperationOutcome",
  • "issue": [
    ]
}