MedTrainer Locations API

openapi: 3.2.0
info:
  title: MedTrainer Public Locations API
  version: 1.0.0
  description: "The MedTrainer Public API allows external integrations to search and manage\ncore directory resources such as locations, divisions, and practitioners.\n\nThis specification describes the available endpoints, request parameters,\npayloads, authentication requirements, and expected responses for clients\nintegrating with the platform.\n\nMost resource endpoints return FHIR-aligned JSON with content type\n`application/fhir+json`. Protected endpoints accept authentication through\neither the `X-API-Key` header or `Authorization: Bearer <token>`.\n\n## Getting started\n\nThis guide walks you through how to generate an API Key from the platform.\nThis key will allow you to authenticate and interact with the available\nAPIs.\n\n## Prerequisites\n\n**Before you begin, make sure you have:**\n\nA valid account and access to the platform\n\nProper permissions to generate an `API Key (Super Admin / Admin)`\n\nLogged into the platform\n\n## Step-by-step\n\n**1. Log in to the platform**\n\nSign in to the MedTrainer platform using your credentials.\n\n**2. Open Organization settings**\n\n**Once you're in:**\n\nOn the left-side menu\n\nClick on **Organization**\n\n**3. Expand “Organization Management” and find the “API keys manager”**\n\n**Inside Organization Settings:**\n\nExpand “Organization Management” menu\n\nHere you’ll find all options to configure the organization\n\nLook for “API keys manager” option and click on it\n\n**4. Create a new API Key group**\n\n**In the “API keys manager” page:**\n\nClick on “Create API key group”\n\nFill the following fields:\n\n`name`\n\n`description`\n\nConfirm the action by clicking the “Create” button.\n\n**5. Activate the API Key “Default”**\n\n**After generating the API key group:**\n\nOn the “API Keys Manager” page, you will see the newly created API key\ngroup, along with a “Default” API key in an “Inactive” status.\n\nTo activate the “Default” API key:\n\nClick on the status to expand the available options.\n\nOnce the list is expanded, select the “Active” status\n\n<div class=\"docs-getting-started-callout docs-getting-started-callout--info\">\n  <span class=\"docs-getting-started-callout__icon\" aria-hidden=\"true\"></span>\n  <span>This API key is required and must be available to use the MedTrainer Public APIs</span>\n</div>\n\n<div class=\"docs-getting-started-callout docs-getting-started-callout--warning\">\n  <span class=\"docs-getting-started-callout__icon\" aria-hidden=\"true\"></span>\n  <span><strong>Important:</strong> Treat your API Key like a password. Keep it private and secure.</span>\n</div>\n\n<div class=\"docs-middle-section-divider\" aria-hidden=\"true\"></div>\n"
servers:
- url: /
  description: Public API base URL
tags:
- name: Locations
  description: Public location lookup and mutation endpoints
paths:
  /api/v1/locations:
    get:
      tags:
      - Locations
      summary: Search locations
      description: 'Returns a FHIR `Bundle` with location resources.

        '
      operationId: searchLocations
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/SearchCount'
      - $ref: '#/components/parameters/SearchPage'
      - $ref: '#/components/parameters/SearchElements'
      responses:
        '200':
          description: Location search results
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/LocationSearchBundle'
              examples:
                default:
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 3
                    link:
                    - relation: self
                      url: /api/v1/locations?_count=2&_page=2&_elements=id%2Cname
                    - relation: first
                      url: /api/v1/locations?_count=2&_page=1&_elements=id%2Cname
                    - relation: previous
                      url: /api/v1/locations?_count=2&_page=1&_elements=id%2Cname
                    - relation: last
                      url: /api/v1/locations?_count=2&_page=2&_elements=id%2Cname
                    entry:
                    - resource:
                        resourceType: Location
                        id: LOC-003
                        name: Location test
                        state: State
                        division:
                          id: DIV-003
                          name: East Division
                        city: City
                        addressLine: Address 1
                        zipCode: '33101'
                        phoneNumber: 0987654321
                        fax: '1234567890'
                        email: test@example.com
                        sendEmail: false
                        enabledCredentialing: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '422':
          $ref: '#/components/responses/SearchValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Locations
      summary: Create a location
      operationId: createLocation
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationCreateRequest'
            examples:
              default:
                value:
                  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:
                    reference: DIV-001
      responses:
        '200':
          $ref: '#/components/responses/LocationCreated'
        '201':
          $ref: '#/components/responses/LocationCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/DivisionWriteNotFound'
        '422':
          $ref: '#/components/responses/LocationValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/LocationBadGateway'
  /api/v1/locations/{publicId}:
    get:
      tags:
      - Locations
      summary: Get a location by public ID
      description: 'Resolves the public location identifier before fetching the resource.

        When `_elements` is provided, only the requested fields are returned.

        '
      operationId: getLocation
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/LocationPublicId'
      - $ref: '#/components/parameters/SearchElements'
      responses:
        '200':
          description: Location resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Location'
              examples:
                default:
                  value:
                    resourceType: Location
                    id: LOC-001
                    name: North Campus
                    addressLine: Address 1
                    city: City
                    state: State
                    division:
                      id: DIV-001
                      name: North Division
                    zipCode: '33101'
                    phoneNumber: 0987654321
                    fax: '1234567890'
                    email: first@test.com
                    sendEmail: false
                    enabledCredentialing: true
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/LocationWriteNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/LocationBadGateway'
    put:
      tags:
      - Locations
      summary: Update a location
      description: 'Resolves the public location identifier before updating the resource.

        '
      operationId: updateLocation
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/LocationPublicId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationUpdateRequest'
            examples:
              default:
                value:
                  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:
                    reference: DIV-001
      responses:
        '200':
          $ref: '#/components/responses/LocationUpdated'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/LocationWriteNotFound'
        '422':
          $ref: '#/components/responses/LocationValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/LocationBadGateway'
    patch:
      tags:
      - Locations
      summary: Update a location with PATCH
      description: 'Resolves the public location identifier before updating the resource

        with the same request body and validation rules as `PUT`.

        '
      operationId: patchLocation
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/LocationPublicId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationUpdateRequest'
            examples:
              default:
                value:
                  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:
                    reference: DIV-001
      responses:
        '200':
          $ref: '#/components/responses/LocationUpdated'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/LocationNotFound'
        '422':
          $ref: '#/components/responses/LocationValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/LocationBadGateway'
components:
  responses:
    LocationWriteNotFound:
      description: Location or linked division resource identifier could not be resolved for a write request
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            locationNotFound:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: not-found
                  details:
                    text: One or more location ids could not be resolved.
            divisionNotFound:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: not-found
                  details:
                    text: One or more division ids could not be resolved.
    ValidationError:
      description: Request validation failed
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            invalidIntegerQuery:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: This value should be of type integer.
                  expression:
                  - _count
            invalidPageLowerBound:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field '_page' must be greater than 0
                  expression:
                  - _page
            invalidElementsType:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field '_elements' must be a comma-separated string
                  expression:
                  - _elements
            missingName:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: The Location.name field is required.
                  expression:
                  - name
            missingDivisionName:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: The Division.name field is required.
                  expression:
                  - name
            missingDivisionLocations:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'locations' is required and must contain at least one location ID string
                  expression:
                  - locations
            invalidLocations:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'locations' must be an array of non-blank location ID strings
                  expression:
                  - locations[1]
            divisionNameTooLong:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'name' must be 100 characters or fewer
                  expression:
                  - name
            duplicateDivisionName:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: This division already exists for this company.
                  expression:
                  - name
            divisionLocationsNotFound:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: All locations must exist and belong to the company.
                  expression:
                  - locations
            divisionLocationsAssigned:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Locations already assigned to another division must first belong to the Default division.
                  expression:
                  - locations
            emptyDivisionUpdatePayload:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: At least one of 'name' or 'locations' must be provided.
                  expression:
                  - name
                  - locations
            missingState:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'state' is required and must be a non-blank string
                  expression:
                  - state
            invalidDivisionReference:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'division.reference' must be a non-blank string
                  expression:
                  - division[reference]
            practitionerResourceType:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'resourceType' must equal "Practitioner"
                  expression:
                  - resourceType
            practitionerBirthDateFormat:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'birthDate' must use MM/DD/YYYY format
                  expression:
                  - birthDate
            practitionerMissingRequiredNestedField:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: The Practitioner.telecom.email field is required.
                  expression:
                  - telecom.email
            practitionerInvalidScalar:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: This value should be of type scalar.
                  expression:
                  - extension.user.location
            practitionerInvalidStatus:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: 'Status must be one of: Active, Inactive, or Deactivated.'
                  expression:
                  - extension.user.status
            practitionerInvalidActiveStatusReason:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: 'Status Reason must be one of: Contracted, Independent, Other for status Active.'
                  expression:
                  - extension.user.statusReason
            practitionerInvalidInactiveStatusReason:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: 'Status Reason must be one of: On Leave, Prospect, Other for status Inactive.'
                  expression:
                  - extension.user.statusReason
            practitionerInvalidDeactivatedStatusReason:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: 'Status Reason must be one of: Deceased, Resigned, Retired, Terminated, Other for status Deactivated.'
                  expression:
                  - extension.user.statusReason
            practitionerIncompatibleStatusReason:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Status Reason "Terminated" is not valid for status "Active".
                  expression:
                  - extension.user.statusReason
            practitionerMissingDeactivatedStatusReason:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Status Reason is required when status is Deactivated.
                  expression:
                  - extension.user.statusReason
            practitionerCreateMultipleIssues:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: The Practitioner.name.given field is required.
                  expression:
                  - name.given
                - severity: error
                  code: invalid
                  details:
                    text: The Practitioner.extension.employment.positionId field is required.
                  expression:
                  - extension.employment.positionId
                - severity: error
                  code: invalid
                  details:
                    text: The Practitioner.extension.user.location field is required.
                  expression:
                  - extension.user.location
            practitionerUnsupportedWriteField:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Field 'extension.employment.employeeCategoryId' is not supported.
                  expression:
                  - extension.employment.employeeCategoryId
            practitionerInvalidDepartmentReference:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: One or more department ids could not be resolved.
                  expression:
                  - extension.employment.departmentId
            practitionerInvalidLocationReference:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: One or more location ids could not be resolved.
                  expression:
                  - extension.user.location
    LocationUpdated:
      description: Location updated successfully
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            default:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: information
                  code: informational
                  details:
                    text: Location updated successfully.
                    id: LOC-001
    LocationValidationError:
      description: Location request validation failed
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            missingName:
              $ref: '#/components/responses/ValidationError/content/application~1fhir+json/examples/missingName'
            missingState:
              $ref: '#/components/responses/ValidationError/content/application~1fhir+json/examples/missingState'
            invalidDivisionReference:
              $ref: '#/components/responses/ValidationError/content/application~1fhir+json/examples/invalidDivisionReference'
    BadRequest:
      description: Request rejected before validation or during request processing
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            invalidJson:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Request payload contains invalid "json" data.
            rejectedByBackingService:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: The request could not be processed.
    LocationBadGateway:
      description: Location identifier or linked division could not be resolved at this time
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            resolverUnavailable:
              $ref: '#/components/responses/BadGateway/content/application~1fhir+json/examples/resolverUnavailable'
            divisionResolutionFailed:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Division reference resolution request failed.
    InvalidOrMissingApiKey:
      description: 'Missing credentials or invalid API key.

        '
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            missingCredentials:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: login
                  details:
                    text: 'Missing or invalid authentication credentials. Provide an API key using the X-API-Key header or Authorization: Bearer <token>.'
            invalidApiKey:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: login
                  details:
                    text: Invalid or revoked API key.
    SearchValidationError:
      description: Search request validation failed
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            invalidIntegerQuery:
              $ref: '#/components/responses/ValidationError/content/application~1fhir+json/examples/invalidIntegerQuery'
            invalidPageLowerBound:
              $ref: '#/components/responses/ValidationError/content/application~1fhir+json/examples/invalidPageLowerBound'
            invalidElementsType:
              $ref: '#/components/responses/ValidationError/content/application~1fhir+json/examples/invalidElementsType'
    LocationCreated:
      description: Location created successfully
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            default:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: information
                  code: informational
                  details:
                    text: Location created successfully.
                    id: LOC-001
    TooManyRequests:
      description: 'Rate limit exceeded.

        '
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            default:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: throttled
                  details:
                    text: Rate limit exceeded. Please retry after a short delay.
    LocationNotFound:
      description: Location or linked division resource was not found
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            locationNotFound:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: not-found
                  details:
                    text: One or more location ids could not be resolved.
            divisionNotFound:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: not-found
                  details:
                    text: Division not found.
    DivisionWriteNotFound:
      description: Division resource identifier could not be resolved for a location write request
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            default:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: not-found
                  details:
                    text: One or more division ids could not be resolved.
    BadGateway:
      description: The requested resource identifier could not be resolved at this time
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            resolverUnavailable:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: invalid
                  details:
                    text: Public id resolution request failed.
    InternalServerError:
      description: Unexpected internal error
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            default:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: exception
                  details:
                    text: An internal server error occurred. Please try again later.
  schemas:
    Location:
      type: object
      additionalProperties: false
      required:
      - resourceType
      properties:
        resourceType:
          type: string
          const: Location
        id:
          type: string
          example: LOC-001
        name:
          type: string
          example: North Campus
        addressLine:
          type: string
          example: 123 Main St
        city:
          type: string
          example: Miami
        state:
          type: string
          example: Florida
        zipCode:
          type: string
          example: '33101'
        phoneNumber:
          type: string
          example: 0987654321
        fax:
          type: string
          example: '1234567890'
        email:
          type: string
          format: email
          example: first@test.com
        sendEmail:
          type: boolean
          example: false
        enabledCredentialing:
          type: boolean
          example: true
        division:
          type: object
          description: Division associated with the location.
          properties:
            id:
              type:

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/openapi/medtrainer-locations-api-openapi.yml