MedTrainer

MedTrainer Practitioner Categories API

Public practitioner category lookup endpoints

GitHub OpenAPI

Operations 2

GET /api/v1/practitioner-categories Search practitioner categories #
GET /api/v1/practitioner-categories/{publicId} Get a practitioner category by public ID #

Documentation

📖
Documentation
https://api.medtrainer.com/docs
📖
APIReference
https://api.medtrainer.com/docs
📖
GettingStarted
https://api.medtrainer.com/docs#section/Getting-started
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/authentication/medtrainer-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/rate-limits/medtrainer-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/openapi/medtrainer-practitioner-categories-api-openapi.yml

Other Resources

🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/errors/medtrainer-problem-types.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/conventions/medtrainer-conventions.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/data-model/medtrainer-data-model.yml
🔗
Conformance
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/conformance/medtrainer-conformance.yml
🔗
Lifecycle
https://raw.githubusercontent.com/api-evangelist/medtrainer/refs/heads/main/lifecycle/medtrainer-lifecycle.yml

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-practitioner-categories-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

medtrainer-practitioner-categories-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: MedTrainer Public Practitioner Categories 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: Practitioner Categories
  description: Public practitioner category lookup endpoints
paths:
  /api/v1/practitioner-categories:
    get:
      tags:
      - Practitioner Categories
      summary: Search practitioner categories
      description: Returns a FHIR `Bundle` with practitioner category resources.
      operationId: searchPractitionerCategories
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/SearchCount'
      - $ref: '#/components/parameters/SearchPage'
      - $ref: '#/components/parameters/PractitionerCategorySearchElements'
      responses:
        '200':
          description: Practitioner category search results
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/PractitionerCategorySearchBundle'
              examples:
                default:
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 3
                    link:
                    - relation: self
                      url: http://localhost/api/v1/practitioner-categories?_count=2&_page=2&_elements=id%2Cname
                    - relation: first
                      url: http://localhost/api/v1/practitioner-categories?_count=2&_page=1&_elements=id%2Cname
                    - relation: previous
                      url: http://localhost/api/v1/practitioner-categories?_count=2&_page=1&_elements=id%2Cname
                    - relation: last
                      url: http://localhost/api/v1/practitioner-categories?_count=2&_page=2&_elements=id%2Cname
                    entry:
                    - resource:
                        resourceType: PractitionerCategory
                        id: PCAT-003
                        name: Operations
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '422':
          $ref: '#/components/responses/SearchValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          description: Practitioner category search request could not be processed
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                default:
                  value:
                    resourceType: OperationOutcome
                    issue:
                    - severity: error
                      code: invalid
                      details:
                        text: The request could not be processed.
                      expression:
                      - _count
  /api/v1/practitioner-categories/{publicId}:
    get:
      tags:
      - Practitioner Categories
      summary: Get a practitioner category by public ID
      description: Resolves the public practitioner category identifier before fetching the resource.
      operationId: getPractitionerCategory
      security:
      - ApiKeyHeader: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PractitionerCategoryPublicId'
      responses:
        '200':
          description: Practitioner category resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/PractitionerCategory'
              examples:
                default:
                  value:
                    resourceType: PractitionerCategory
                    id: PCAT-001
                    name: Nursing
        '401':
          $ref: '#/components/responses/InvalidOrMissingApiKey'
        '404':
          $ref: '#/components/responses/PractitionerCategoryNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          description: Practitioner category identifier could not be resolved
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                default:
                  value:
                    resourceType: OperationOutcome
                    issue:
                    - severity: error
                      code: invalid
                      details:
                        text: The request could not be processed.
                      expression:
                      - publicId
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: 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
    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.
    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.
    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.
    PractitionerCategoryNotFound:
      description: Practitioner category resource was not found
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          examples:
            default:
              value:
                resourceType: OperationOutcome
                issue:
                - severity: error
                  code: not-found
                  details:
                    text: Practitioner category not found.
    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'
  parameters:
    PractitionerCategoryPublicId:
      name: publicId
      in: path
      required: true
      description: Public practitioner category identifier.
      schema:
        type: string
        example: PCAT-001
    SearchPage:
      name: _page
      in: query
      required: false
      description: 1-based page number. Must be a positive integer.
      schema:
        type: integer
        minimum: 1
        default: 1
    PractitionerCategorySearchElements:
      name: _elements
      in: query
      required: false
      description: 'Comma-separated field selector for practitioner category search.


        The only implemented selectors for this endpoint are `id` and `name`.

        When `_elements` is omitted, practitioner category resources default to

        `id,name`.


        Whitespace around values is trimmed. Unknown selectors are preserved in

        pagination links but ignored when each resource is built.

        '
      schema:
        type: string
        example: id,name
    SearchCount:
      name: _count
      in: query
      required: false
      description: Number of resources to return. Must be a positive integer.
      schema:
        type: integer
        minimum: 1
        default: 20
  schemas:
    OperationOutcome:
      type: object
      additionalProperties: false
      required:
      - resourceType
      - issue
      properties:
        resourceType:
          type: string
          const: OperationOutcome
        issue:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OperationOutcomeIssue'
    PractitionerCategorySearchBundle:
      type: object
      additionalProperties: false
      required:
      - resourceType
      - type
      - total
      - link
      - entry
      properties:
        resourceType:
          type: string
          const: Bundle
        type:
          type: string
          const: searchset
        total:
          type: integer
          minimum: 0
        link:
          type: array
          items:
            $ref: '#/components/schemas/BundleLink'
        entry:
          type: array
          items:
            $ref: '#/components/schemas/PractitionerCategorySearchEntry'
    PractitionerCategorySearchEntry:
      type: object
      additionalProperties: false
      required:
      - resource
      properties:
        resource:
          $ref: '#/components/schemas/PractitionerCategory'
    BundleLink:
      type: object
      additionalProperties: false
      required:
      - relation
      - url
      properties:
        relation:
          type: string
          enum:
          - self
          - first
          - previous
          - next
          - last
        url:
          type: string
          format: uri
    OperationOutcomeDetails:
      type: object
      additionalProperties: false
      required:
      - text
      properties:
        text:
          type: string
        id:
          type: string
    OperationOutcomeIssue:
      type: object
      additionalProperties: false
      required:
      - severity
      - code
      - details
      properties:
        severity:
          type: string
          enum:
          - fatal
          - error
          - warning
          - information
        code:
          type: string
          example: invalid
        details:
          $ref: '#/components/schemas/OperationOutcomeDetails'
        expression:
          type: array
          items:
            type: string
    PractitionerCategory:
      type: object
      additionalProperties: false
      required:
      - resourceType
      properties:
        resourceType:
          type: string
          const: PractitionerCategory
        id:
          type: string
          example: PCAT-001
        name:
          type:
          - string
          - 'null'
          example: Nursing
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Preferred authentication header for protected endpoints.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Alternative authentication scheme using `Authorization: Bearer <token>`.'