MedTrainer Practitioners API

openapi: 3.2.0
info:
  title: MedTrainer Public Practitioners 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: Practitioners
  description: Public practitioner lookup, search, and mutation endpoints
paths:
  /api/v1/practitioner:
    post:
      tags:
      - Practitioners
      summary: Create a practitioner
      description: '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.

        '
      operationId: createPractitioner
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PractitionerWriteRequest'
            examples:
              default:
                value:
                  resourceType: Practitioner
                  name:
                    given: John
                    family: Doe
                    middle: Allen
                    other:
                      given: Jonathan
                      middle: Alpha
                      family: Public
                      suffix: III
                      usageStartDate: 02/14/2001
                      usageEndDate: 02/14/2005
                  birthDate: 01/01/1990
                  gender: male
                  telecom:
                    email: john.payload1@example.com
                    primaryEmail: john.primary@example.com
                    personalEmail: john.personal@example.com
                    ccEmail1: john.cc1@example.com
                    ccEmail2: john.cc2@example.com
                    cellPhone: '3055550111'
                    homePhone: '3055550103'
                    workPhone: '3055550104'
                    fax: '3055550105'
                  address:
                    line:
                    - Main Street 1
                    - Suite 10
                    city: Miami
                    state: FL
                    postalCode: '33101'
                    country: United States
                    county: Miami-Dade
                  mailingAddress:
                    line:
                    - Billing Street 9
                    - Floor 4
                    city: Orlando
                    state: FL
                    postalCode: '32801'
                    country: United States
                    county: Orange
                    province: N/A
                  extension:
                    employment:
                      positionId: pos770
                      departmentId: dep1
                      hireDate: 06/15/2020
                      terminationDate: 06/15/2025
                    user:
                      location: loc4857
                      userType: admin
                      password: <set-at-request-time>
                      status: Active
                      statusReason: Contracted
                      ssn: '123456789'
                      birthPlace:
                        country: United States
                        stateOther: Nuevo Leon
                        city: Monterrey
                      citizenship: United States
                      raceEthnicity: Hispanic or Latino
                      languages:
                      - Spanish
                      - French
                      - German
                      fnin:
                        number: FNIN12
                        countryIssue: United States
                    provider:
                      npiNumber: '1234567890'
                      caqhId: '1234567890'
                      caqhUsername: caqh_user
                      caqhPassword: <set-at-request-time>
                      caqhLastReattestationDate: 03/01/2026
                      caqhEmail: caqh.provider@example.com
                      treatsGender: Both
                      patientAgeMinimum: 18
                      patientAgeMaximum: 65
                      upin: UPIN12
      responses:
        '200':
          $ref: '#/components/responses/PractitionerCreated'
        '201':
          $ref: '#/components/responses/PractitionerCreated'
        '400':
          $ref: '#/components/responses/PractitionerBadRequest'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '422':
          $ref: '#/components/responses/PractitionerWriteValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Practitioners
      summary: Search practitioners
      description: '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.

        '
      operationId: searchPractitioners
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/SearchCount'
      - $ref: '#/components/parameters/SearchPage'
      - $ref: '#/components/parameters/SearchElements'
      responses:
        '200':
          description: Practitioner search results
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/PractitionerSearchBundle'
              examples:
                filtered:
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 3
                    link:
                    - relation: self
                      url: /api/v1/practitioner?_count=2&_page=2&_elements=name%2Ctelecom.email%2Ctelecom.homePhone
                    - relation: first
                      url: /api/v1/practitioner?_count=2&_page=1&_elements=name%2Ctelecom.email%2Ctelecom.homePhone
                    - relation: previous
                      url: /api/v1/practitioner?_count=2&_page=1&_elements=name%2Ctelecom.email%2Ctelecom.homePhone
                    - relation: last
                      url: /api/v1/practitioner?_count=2&_page=2&_elements=name%2Ctelecom.email%2Ctelecom.homePhone
                    entry:
                    - resource:
                        resourceType: Practitioner
                        name:
                          given: Katherine
                          family: Johnson
                        telecom:
                          email: katherine@example.test
                          homePhone: '3055550103'
                full:
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                    - relation: self
                      url: /api/v1/practitioner?_count=20&_page=1
                    - relation: first
                      url: /api/v1/practitioner?_count=20&_page=1
                    - relation: last
                      url: /api/v1/practitioner?_count=20&_page=1
                    entry:
                    - resource:
                        resourceType: Practitioner
                        id: PRAC-001
                        name:
                          given: Ada
                          family: Lovelace
                          middle: Byron
                          other:
                            given: Augusta
                            middle: Ada
                            family: King
                            suffix: Countess
                            usageStartDate: 02/14/2001
                            usageEndDate: 02/14/2005
                        telecom:
                          email: ada@example.test
                          primaryEmail: ada.primary@example.test
                          personalEmail: ada.personal@example.test
                          cellPhone: '3055550111'
                          homePhone: '3055550103'
                          workPhone: '3055550104'
                          fax: '3055550105'
                        birthDate: 01/01/1990
                        gender: Female
                        address:
                          line:
                          - Main Street 1
                          - Suite 10
                          city: Miami
                          state: FL
                          postalCode: '33101'
                          country: United States
                          county: Miami-Dade
                        mailingAddress:
                          line:
                          - Billing Street 9
                          - Floor 4
                          city: Orlando
                          state: FL
                          postalCode: '32801'
                          country: United States
                          county: Orange
                          province: N/A
                        departments:
                        - id: DEPT-091
                          name: Mathematics
                        position:
                          id: POS-011
                          name: Analyst
                        locations:
                        - id: LOC-420
                          name: London Clinic
                        divisions:
                        - id: DIV-007
                          name: Clinical Operations
                        extension:
                          user:
                            status: Active
                            statusReason: Contracted
                            userType: admin
                            location: LOC-420
                          provider:
                            npiNumber: '1234567890'
                nestedElements:
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                    - relation: self
                      url: /api/v1/practitioner?_count=20&_page=1&_elements=extension.user.status%2Cextension.user.statusReason%2Cextension.user.location%2Cextension.provider.npiNumber
                    - relation: first
                      url: /api/v1/practitioner?_count=20&_page=1&_elements=extension.user.status%2Cextension.user.statusReason%2Cextension.user.location%2Cextension.provider.npiNumber
                    - relation: last
                      url: /api/v1/practitioner?_count=20&_page=1&_elements=extension.user.status%2Cextension.user.statusReason%2Cextension.user.location%2Cextension.provider.npiNumber
                    entry:
                    - resource:
                        resourceType: Practitioner
                        extension:
                          user:
                            status: Active
                            statusReason: Contracted
                            location: 420
                          provider:
                            npiNumber: '1234567890'
        '400':
          $ref: '#/components/responses/PractitionerBadRequest'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '422':
          $ref: '#/components/responses/PractitionerReadValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/practitioner/{publicId}:
    get:
      tags:
      - Practitioners
      summary: Get a practitioner by public ID
      description: '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.

        '
      operationId: getPractitioner
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PractitionerPublicId'
      - $ref: '#/components/parameters/SearchElements'
      responses:
        '200':
          description: Practitioner resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Practitioner'
              examples:
                filtered:
                  value:
                    resourceType: Practitioner
                    name:
                      given: Ada
                      family: Lovelace
                    telecom:
                      email: ada@example.test
                      homePhone: '3055550103'
                default:
                  value:
                    resourceType: Practitioner
                    id: PRAC-001
                    name:
                      given: Ada
                      family: Lovelace
                      middle: Byron
                      other:
                        given: Augusta
                        middle: Ada
                        family: King
                        suffix: Countess
                        usageStartDate: 02/14/2001
                        usageEndDate: 02/14/2005
                    birthDate: 01/01/1990
                    gender: Female
                    departments:
                    - id: DEPT-091
                      name: Mathematics
                    position:
                      id: POS-011
                      name: Analyst
                    locations:
                    - id: LOC-420
                      name: London Clinic
                    divisions:
                    - id: DIV-007
                      name: Clinical Operations
                    telecom:
                      email: ada@example.test
                      primaryEmail: ada.primary@example.test
                      personalEmail: ada.personal@example.test
                      cellPhone: '3055550111'
                      homePhone: '3055550103'
                      workPhone: '3055550104'
                      fax: '3055550105'
                    address:
                      line:
                      - Main Street 1
                      - Suite 10
                      city: Miami
                      state: FL
                      postalCode: '33101'
                      country: United States
                      county: Miami-Dade
                    mailingAddress:
                      line:
                      - Billing Street 9
                      - Floor 4
                      city: Orlando
                      state: FL
                      postalCode: '32801'
                      country: United States
                      county: Orange
                      province: N/A
                    extension:
                      user:
                        status: Active
                        statusReason: Contracted
                        userType: admin
                        location: LOC-420
                      provider:
                        npiNumber: '1234567890'
                nestedElements:
                  value:
                    resourceType: Practitioner
                    extension:
                      user:
                        status: Active
                        statusReason: Contracted
                        location: 420
                      provider:
                        npiNumber: '1234567890'
        '400':
          $ref: '#/components/responses/PractitionerBadRequest'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/PractitionerNotFound'
        '422':
          $ref: '#/components/responses/PractitionerReadValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
    put:
      tags:
      - Practitioners
      summary: Update a practitioner
      description: '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.

        '
      operationId: updatePractitioner
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PractitionerPublicId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PractitionerUpdateRequest'
            examples:
              default:
                value:
                  resourceType: Practitioner
                  name:
                    given: John
                    family: Doe
                    middle: Allen
                    other:
                      given: Jonathan
                      middle: Alpha
                      family: Public
                      suffix: III
                      usageStartDate: 02/14/2001
                      usageEndDate: 02/14/2005
                  birthDate: 01/01/1990
                  gender: male
                  telecom:
                    email: john.payload1@example.com
                    primaryEmail: john.primary@example.com
                    personalEmail: john.personal@example.com
                    ccEmail1: john.cc1@example.com
                    ccEmail2: john.cc2@example.com
                    cellPhone: '3055550111'
                    homePhone: '3055550103'
                    workPhone: '3055550104'
                    fax: '3055550105'
                  address:
                    line:
                    - Main Street 1
                    - Suite 10
                    city: Miami
                    state: FL
                    postalCode: '33101'
                    country: United States
                    county: Miami-Dade
                  mailingAddress:
                    line:
                    - Billing Street 9
                    - Floor 4
                    city: Orlando
                    state: FL
                    postalCode: '32801'
                    country: United States
                    county: Orange
                    province: N/A
                  extension:
                    employment:
                      positionId: pos770
                      departmentId: dep1
                      hireDate: 06/15/2020
                      terminationDate: 06/15/2025
                    user:
                      location: loc4857
                      userType: admin
                      password: <set-at-request-time>
                      status: Active
                      statusReason: Contracted
                      ssn: '123456789'
                      birthPlace:
                        country: United States
                        stateOther: Nuevo Leon
                        city: Monterrey
                      citizenship: United States
                      raceEthnicity: Hispanic or Latino
                      languages:
                      - Spanish
                      - French
                      - German
                      fnin:
                        number: FNIN12
                        countryIssue: United States
                    provider:
                      npiNumber: '1234567890'
                      caqhId: '1234567890'
                      caqhUsername: caqh_user
                      caqhPassword: <set-at-request-time>
                      caqhLastReattestationDate: 03/01/2026
                      caqhEmail: caqh.provider@example.com
                      treatsGender: Both
                      patientAgeMinimum: 18
                      patientAgeMaximum: 65
                      upin: UPIN12
      responses:
        '200':
          $ref: '#/components/responses/PractitionerUpdated'
        '400':
          $ref: '#/components/responses/PractitionerBadRequest'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/PractitionerNotFound'
        '422':
          $ref: '#/components/responses/PractitionerWriteValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
      - Practitioners
      summary: Update a practitioner with PATCH
      description: '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.

        '
      operationId: patchPractitioner
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PractitionerPublicId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PractitionerUpdateRequest'
            examples:
              default:
                value:
                  resourceType: Practitioner
                  name:
                    given: John
                    family: Doe
                    middle: Allen
                    other:
                      given: Jonathan
                      middle: Alpha
                      family: Public
                      suffix: III
                      usageStartDate: 02/14/2001
                      usageEndDate: 02/14/2005
                  birthDate: 01/01/1990
                  gender: male
                  telecom:
                    email: john.payload1@example.com
                    primaryEmail: john.primary@example.com
                    personalEmail: john.personal@example.com
                    ccEmail1: john.cc1@example.com
                    ccEmail2: john.cc2@example.com
                    cellPhone: '3055550111'
                    homePhone: '3055550103'
                    workPhone: '3055550104'
                    fax: '3055550105'
                  address:
                    line:
                    - Main Street 1
                    - Suite 10
                    city: Miami
                    state: FL
                    postalCode: '33101'
                    country: United States
                    county: Miami-Dade
                  mailingAddress:
                    line:
                    - Billing Street 9
                    - Floor 4
                    city: Orlando
                    state: FL
                    postalCode: '32801'
                    country: United States
                    county: Orange
                    province: N/A
                  extension:
                    employment:
                      positionId: pos770
                      departmentId: dep1
                      hireDate: 06/15/2020
                      terminationDate: 06/15/2025
                    user:
                      location: loc4857
                      userType: admin
                      password: <set-at-request-time>
                      status: Active
                      statusReason: Contracted
                      ssn: '123456789'
                      birthPlace:
                        country: United States
                        stateOther: Nuevo Leon
                        city: Monterrey
                      citizenship: United States
                      raceEthnicity: Hispanic or Latino
                      languages:
                      - Spanish
                      - French
                      - German
                      fnin:
                        number: FNIN12
                        countryIssue: United States
                    provider:
                      npiNumber: '1234567890'
                      caqhId: '1234567890'
                      caqhUsername: caqh_user
                      caqhPassword: <set-at-request-time>
                      caqhLastReattestationDate: 03/01/2026
                      caqhEmail: caqh.provider@example.com
                      treatsGender: Both
                      patientAgeMinimum: 18
                      patientAgeMaximum: 65
                      upin: UPIN12
      responses:
        '200':
          $ref: '#/components/responses/PractitionerUpdated'
        '400':
          $ref: '#/components/responses/PractitionerBadRequest'
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/PractitionerNotFound'
        '422':
          $ref: '#/components/responses/PractitionerWriteValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PractitionerLinkedResource:
      type: object
      additionalProperties: false
      description: Related practitioner resource. `name` may be absent when it is not available.
      required:
      - id
      properties:
        id:
          type: string
          example: LOC-420
        name:
          type: string
          example: London Clinic
    PractitionerWriteMailingAddress:
      type: object
      description: "Optional mailing address payload.\n\nThe server enforces:\n  - a character allowlist regex `^[A-Za-z0-9 .'\\-]+$` on `line[0]`,\n    `line[1]`, and `city`\n  - `maxLength: 100` on `county` and `province`\n"
      properties:
        line:
          type: array
          maxItems: 2
          items:
            type: string
            minLength: 1
            maxLength: 150
        city:
          type: string
          minLength: 1
          maxLength: 50
        state:
          type: string
          minLength: 1
          maxLength: 50
        postalCode:
          type: string
          minLength: 5
          maxLength: 5
          pattern: ^\d{5}$
          description: Exactly 5 digits.
        country:
          type: string
          minLength: 1
        county:
          type: string
          minLength: 1
          maxLength: 100
        province:
          type: string
          minLength: 1
          maxLength: 100
    PractitionerSearchEntry:
      type: object
      additionalProperties: false
      required:
      - resource
      properties:
        resource:
          $ref: '#/components/schemas/Practitioner'
    PractitionerWriteProviderExtension:
      type: object
      description: 'Optional provider extension payload.

        '
      properties:
        npiNumber:
          type: string
          minLength: 10
          maxLength: 10
          pattern: ^\d{10}$
        caqhId:
          type: string
          minLength: 1
          maxLength: 12
        caqhUsername:
          type: string
          minLength: 1
          maxLength: 50
        caqhPassword:
          type: string
          minLength: 1
          maxLength: 50
        caqhLastReattestationDate:
          $ref: '#/components/schemas/MmDdYyyyDateString'
        caqhEmail:
          type: string
          minLength: 1
          format: email
        treatsGender:
          type: string
          minLength: 1
          description: Accepted values are `Male only`, `Female only`, and `Both`.
          enum:
          - Male only
          - Female only
          - Both
        patientAgeMinimum:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 100
          - type: string
            pattern: ^\d+$
            description: Numeric string representing an integer between 0 and 100 inclusive.
          description: Must be an integer (or numeric string) in the range `[0, 100]`. Booleans and non-numeric strings are rejected.
        patientAgeMaximum:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 100
          - type: string
            pattern: ^\d+$
            description: Numeric string representing an integer between 0 and 100 inclusive.
          description: Must be an integer (or numeric string) in the range `[0, 100]`. Booleans and non-numeric strings are rejected.
        upin:
          type: string
          minLength: 1
          maxLength: 6
          pattern: ^[A-Za-z0-9 .'\-]+$
          description: Only letters, numbers, spaces, apos

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