MedTrainer

MedTrainer Practitioners API

Public practitioner lookup, search, and mutation endpoints

Documentation GitHub OpenAPI

Operations 5

POST /api/v1/practitioner Create a practitioner #

GET /api/v1/practitioner Search practitioners #

GET /api/v1/practitioner/{publicId} Get a practitioner by public ID #

PUT /api/v1/practitioner/{publicId} Update a practitioner #

PATCH /api/v1/practitioner/{publicId} Update a practitioner with PATCH #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/medtrainer-practitioners-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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

    core directory resources such as locations, divisions, and practitioners.'
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:
  responses:
    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: er

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