openapi: '3.1.1'
info:
  title: USMLE API
  description: Provides access to physician USMLE information.
  version: '1.0'
servers:
  - url: https://services-usmle-demo.fsmb.org/
paths:
  /connect/token:
    post:
      tags:
        - Token
      summary: Authentication endpoint.
      responses:
        '200':
          description: The Authentication response.
  '/v1/{board}/transcripts/{usmleId}/current':
    get:
      tags:
        - Transcripts
      summary: Get Current Transcript
      description: Gets the current transcript for a physician.
      parameters:
        - name: board
          in: path
          description: Board code (default = 'me')
          required: true
          schema:
            title: String
            type: string
            default: me
        - name: usmleId
          in: path
          description: USMLE ID of the practitioner
          required: true
          schema:
            title: String
            type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Transcript'
            application/json:
              schema:
                $ref: '#/components/schemas/Transcript'
            text/json:
              schema:
                $ref: '#/components/schemas/Transcript'
        '204':
          description: There is no transcript for the physician
        '403':
          description: Board code is invalid
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '400':
          description: USMLE ID is invalid
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
  '/v1/{board}/transcripts/summary':
    get:
      tags:
        - Transcripts
      summary: Get summary of available transcripts
      description: Gets a summary of available transcripts given the criteria.
      parameters:
        - name: board
          in: path
          description: Board code (default = 'me')
          required: true
          schema:
            title: String
            type: string
            default: me
        - name: fromDate
          in: query
          description: 'Start date, inclusive'
          schema:
            title: DateTime
            type: string
            format: date-time
        - name: toDate
          in: query
          description: 'End date, inclusive'
          schema:
            title: DateTime
            type: string
            format: date-time
        - name: $orderBy
          in: query
          schema:
            title: String
            type: string
            default: sentDate
        - name: $offset
          in: query
          schema:
            title: Int32
            maximum: 2147483647
            minimum: 0
            type: integer
            format: int32
            default: 0
        - name: $limit
          in: query
          schema:
            title: Int32
            maximum: 2147483647
            minimum: 1
            type: integer
            format: int32
            default: 100
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                title: TranscriptSummaryIEnumerable
                type: array
                items:
                  $ref: '#/components/schemas/TranscriptSummary'
            application/json:
              schema:
                title: TranscriptSummaryIEnumerable
                type: array
                items:
                  $ref: '#/components/schemas/TranscriptSummary'
            text/json:
              schema:
                title: TranscriptSummaryIEnumerable
                type: array
                items:
                  $ref: '#/components/schemas/TranscriptSummary'
        '403':
          description: Board code is invalid
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '400':
          description: Criteria is bad
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
  '/v1/{board}/transcripts/{usmleId}/files/usmle':
    get:
      tags:
        - Transcripts
      summary: Get USMLE Transcript File
      description: Gets the USMLE Transcript file.
      parameters:
        - name: board
          in: path
          description: Board code (default = 'me')
          required: true
          schema:
            title: String
            type: string
            default: me
        - name: usmleId
          in: path
          description: USMLE ID of the practitioner
          required: true
          schema:
            title: String
            type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                title: 'Array[]'
                type: string
                format: byte
            application/json:
              schema:
                title: 'Array[]'
                type: string
                format: byte
            text/json:
              schema:
                title: 'Array[]'
                type: string
                format: byte
        '403':
          description: Board code is invalid
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '400':
          description: USMLE ID is invalid
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
  '/v1/{board}/transcripts/{usmleId}':
    post:
      tags:
        - Transcripts
      summary: Request New Transcript
      description: "Requests a new transcript be generated for the given USMLE ID. Transcripts can take 24 hours or more to be created.\r\n\r\nA new transcript can only be requested if the following conditions apply:\r\n- The physician has previously requested a transcript to the entity\r\n- The transcript has not expired\r\n- A new transcript is not already being created"
      parameters:
        - name: board
          in: path
          description: Board code (default = 'me')
          required: true
          schema:
            title: String
            type: string
            default: me
        - name: usmleId
          in: path
          description: USMLE ID of the practitioner
          required: true
          schema:
            title: String
            type: string
      responses:
        '201':
          description: Created
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Transcript'
            application/json:
              schema:
                $ref: '#/components/schemas/Transcript'
            text/json:
              schema:
                $ref: '#/components/schemas/Transcript'
        '403':
          description: Board code is invalid
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '400':
          description: USMLE ID is invalid or no USMLE transcripts available
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Physician does not have a previous request or it has expired
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: 'A new transcript has already been requested recently, wait for a while and try again'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
components:
  schemas:
    BoardActions:
      title: BoardActions
      type: object
      properties:
        hasBoardActions:
          title: Boolean
          type: boolean
          description: Indicates if the physician has board actions.
        boardActionDescription:
          title: String
          maxLength: 500
          type:
            - 'null'
            - string
          description: Board action description
      description: Board action information
    EcfmgInformation:
      title: EcfmgInformation
      type: object
      properties:
        hasPartHistory:
          title: Boolean
          type: boolean
          description: Indicates if ECFMG part history is available
        partHistoryDescription:
          title: String
          maxLength: 500
          type:
            - 'null'
            - string
          description: ECFMG part history description
        hasLastCsa:
          title: Boolean
          type: boolean
          description: Indicates if ECFMG last CSA is available
        lastCsaDescription:
          title: String
          maxLength: 500
          type:
            - 'null'
            - string
          description: ECFMG last CSA description
      description: ECFMG information
    Exam:
      title: Exam
      required:
        - examCode
        - examDescription
      type: object
      properties:
        examCode:
          title: String
          maxLength: 10
          minLength: 1
          type: string
          description: Exam code
        examDescription:
          title: String
          maxLength: 100
          minLength: 1
          type: string
          description: Exam description
        examDate:
          title: DateTime
          type: string
          description: Date exam was taken
          format: date-time
        passFailStatus:
          title: String
          maxLength: 20
          type:
            - 'null'
            - string
          description: 'Pass/fail status (e.g. `Pass`, `Fail`, `Undetermined`'
        score:
          title: Int32Nullable
          type:
            - 'null'
            - integer
          description: Score
          format: int32
        minimumPassScore:
          title: Int32Nullable
          type:
            - 'null'
            - integer
          description: Minimum passing score
          format: int32
        note:
          title: String
          maxLength: 1000
          type:
            - 'null'
            - string
          description: Note
        scoreAvailableDate:
          title: DateTime
          type: string
          description: Date score is available
          format: date-time
        hasIrregularBehavior:
          title: Boolean
          type: boolean
          description: Is there irregular behavior?
        irregularBehavior:
          title: IrregularBehaviorIEnumerable
          type:
            - 'null'
            - array
          items:
            $ref: '#/components/schemas/IrregularBehavior'
          description: Irregular behavior
      description: Exam history
    ExamSummary:
      title: ExamSummary
      required:
        - step1
        - step2
        - step2CS
        - step2CK
        - step3
      type: object
      properties:
        step1:
          description: Step1 exam summary
          $ref: '#/components/schemas/ExamSummaryDetail'
        step2:
          description: Step2 exam summary
          $ref: '#/components/schemas/ExamSummaryDetail'
        step2CS:
          description: Step2 CS exam summary
          $ref: '#/components/schemas/ExamSummaryDetail'
        step2CK:
          description: Step2 CK exam summary
          $ref: '#/components/schemas/ExamSummaryDetail'
        step3:
          description: Step3 exam summary
          $ref: '#/components/schemas/ExamSummaryDetail'
      description: Exam summary
    ExamSummaryDetail:
      title: ExamSummaryDetail
      type: object
      properties:
        lastExamDate:
          title: DateTimeNullable
          type:
            - 'null'
            - string
          description: Date exam was last taken
          format: date-time
        lastPassFailStatus:
          title: String
          maxLength: 20
          type:
            - 'null'
            - string
          description: 'Pass/fail status (e.g. `Pass`, `Fail`, `Undetermined` of last exam'
        attempts:
          title: Int32
          type: integer
          description: Number of attempts
          format: int32
      description: Exam summary
    FlexInformation:
      title: FlexInformation
      type: object
      properties:
        hasFlex:
          title: Boolean
          type: boolean
          description: Indicates if FLEX is available
        flexDescription:
          title: String
          maxLength: 500
          type:
            - 'null'
            - string
          description: FLEX description
      description: FLEX information
    IceInformation:
      title: IceInformation
      type: object
      properties:
        hasIce:
          title: Boolean
          type: boolean
          description: Indicates if ICE is available
        iceDescription:
          title: String
          maxLength: 500
          type:
            - 'null'
            - string
          description: ICE description
      description: ICE information
    Identification:
      title: Identification
      type: object
      properties:
        birthDate:
          title: DateTimeNullable
          type:
            - 'null'
            - string
          description: Date of birth
          format: date-time
      description: Identity information
    IrregularBehavior:
      title: IrregularBehavior
      required:
        - description
        - note
      type: object
      properties:
        description:
          title: String
          maxLength: 100
          minLength: 1
          type: string
          description: Irregular behavior description
        note:
          title: String
          maxLength: 1000
          minLength: 1
          type: string
          description: Irregular behavior note
      description: Irregular behavior
    Name:
      title: Name
      required:
        - firstName
        - lastName
        - isSingularName
      type: object
      properties:
        firstName:
          title: String
          maxLength: 50
          minLength: 1
          type: string
          description: First name
        middleName:
          title: String
          maxLength: 50
          type:
            - 'null'
            - string
          description: Middle name
        lastName:
          title: String
          maxLength: 50
          minLength: 1
          type: string
          description: Last name
        suffix:
          title: String
          maxLength: 4
          type:
            - 'null'
            - string
          description: 'Suffix (optional, e.g. Jr, Sr)'
        isSingularName:
          title: Boolean
          type: boolean
      description: Name of a person
    NbmeInformation:
      title: NbmeInformation
      type: object
      properties:
        hasPartHistory:
          title: Boolean
          type: boolean
          description: Indicates if NBME part history is available
        partHistoryDescription:
          title: String
          maxLength: 500
          type:
            - 'null'
            - string
          description: NBME part history description
      description: NBME information
    ProblemDetails:
      title: ProblemDetails
      type: object
      properties:
        type:
          title: String
          type:
            - 'null'
            - string
        title:
          title: String
          type:
            - 'null'
            - string
        status:
          title: Int32Nullable
          type:
            - 'null'
            - integer
          format: int32
        detail:
          title: String
          type:
            - 'null'
            - string
        instance:
          title: String
          type:
            - 'null'
            - string
    Recipient:
      title: Recipient
      required:
        - name
        - stateOrProvince
      type: object
      properties:
        name:
          title: String
          maxLength: 100
          minLength: 1
          type: string
          description: Recipient name
        addressLines:
          title: StringIEnumerable
          type:
            - 'null'
            - array
          items:
            title: String
            type: string
          description: Address lines
        city:
          title: String
          maxLength: 50
          type:
            - 'null'
            - string
          description: City
        stateOrProvince:
          description: State or province
          $ref: '#/components/schemas/StateOrProvince'
        postalCode:
          title: String
          maxLength: 9
          type:
            - 'null'
            - string
          description: Postal code
      description: Recipient information
    StateOrProvince:
      title: StateOrProvince
      required:
        - code
        - description
      type: object
      properties:
        code:
          title: String
          maxLength: 3
          minLength: 1
          type: string
          description: State or province code
        description:
          title: String
          maxLength: 100
          minLength: 1
          type: string
          description: Description
        countryCode:
          title: String
          maxLength: 2
          type:
            - 'null'
            - string
          description: ISO country code
        countryDescription:
          title: String
          maxLength: 100
          type:
            - 'null'
            - string
          description: COuntry description
      description: State or province
    Transcript:
      title: Transcript
      required:
        - usmleId
        - fid
        - recipient
        - information
        - legalName
        - identity
        - exams
        - examSummary
        - boardActions
        - nbme
        - ecfmg
        - flex
        - ice
        - usmle
      type: object
      properties:
        usmleId:
          title: String
          maxLength: 8
          minLength: 1
          type: string
          description: USMLE ID
        fid:
          title: String
          maxLength: 9
          minLength: 1
          type: string
          description: FID of physician
        recipient:
          description: Recipient information
          $ref: '#/components/schemas/Recipient'
        information:
          description: Transcript information
          $ref: '#/components/schemas/TranscriptInformation'
        legalName:
          description: Legal name
          $ref: '#/components/schemas/Name'
        identity:
          description: Identity information
          $ref: '#/components/schemas/Identification'
        otherNames:
          title: NameIEnumerable
          type:
            - 'null'
            - array
          items:
            $ref: '#/components/schemas/Name'
          description: Other names
        exams:
          title: ExamIEnumerable
          type: array
          items:
            $ref: '#/components/schemas/Exam'
          description: Exam history
        examSummary:
          description: Exam history summary
          $ref: '#/components/schemas/ExamSummary'
        hasNonAdministrativeIrregularBehavior:
          title: Boolean
          type: boolean
          description: Is there non-administrative irregular behavior?
        nonAdministrativeIrregularBehavior:
          title: IrregularBehaviorIEnumerable
          type:
            - 'null'
            - array
          items:
            $ref: '#/components/schemas/IrregularBehavior'
          description: Non-administrative Irregular behavior
        boardActions:
          description: Board action information
          $ref: '#/components/schemas/BoardActions'
        nbme:
          description: NBME information
          $ref: '#/components/schemas/NbmeInformation'
        ecfmg:
          description: ECFMG information
          $ref: '#/components/schemas/EcfmgInformation'
        flex:
          description: FLEX information
          $ref: '#/components/schemas/FlexInformation'
        ice:
          description: ICE information
          $ref: '#/components/schemas/IceInformation'
        usmle:
          description: USMLE information
          $ref: '#/components/schemas/UsmleInformation'
      description: Physician transcript
    TranscriptInformation:
      title: TranscriptInformation
      type: object
      properties:
        hasFcvsProfile:
          title: Boolean
          type: boolean
          description: Determines if an FCVS profile was released
        fcvsReleaseDate:
          title: DateTimeNullable
          type:
            - 'null'
            - string
          description: 'Date the FCVS profile was released, if any'
          format: date-time
        fcvsReleaseDateUtc:
          title: DateTimeNullable
          type:
            - 'null'
            - string
          description: 'Datetime, in UTC, the FCVS profile was released, if any'
          format: date-time
        hasTranscriptRequest:
          title: Boolean
          type: boolean
          description: Determines if a standalone transcript request was sent
        transcriptSentDate:
          title: DateTimeNullable
          type:
            - 'null'
            - string
          description: 'Date the transcript was sent, if any'
          format: date-time
        transcriptSentDateUtc:
          title: DateTimeNullable
          type:
            - 'null'
            - string
          description: 'Datetime, in UTC, the transcript was sent, if any'
          format: date-time
      description: Transcript information
    TranscriptSummary:
      title: TranscriptSummary
      required:
        - usmleId
        - fid
        - information
        - legalName
        - examSummary
      type: object
      properties:
        usmleId:
          title: String
          maxLength: 8
          minLength: 1
          type: string
          description: USMLE ID
        fid:
          title: String
          maxLength: 9
          minLength: 1
          type: string
          description: FID of physician
        sentDate:
          title: DateTime
          type: string
          description: Sent date
          format: date-time
        sentDateUtc:
          title: DateTime
          type: string
          description: 'Sent datetime, in UTC'
          format: date-time
        information:
          description: Transcript information
          $ref: '#/components/schemas/TranscriptInformation'
        legalName:
          description: Legal name
          $ref: '#/components/schemas/Name'
        examSummary:
          description: Exam history summary
          $ref: '#/components/schemas/ExamSummary'
      description: Physician transcript summary
    UsmleInformation:
      title: UsmleInformation
      type: object
      properties:
        step2CSDescription:
          title: String
          maxLength: 1000
          type:
            - 'null'
            - string
          description: Step2 CS description
      description: USMLE information
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          authorizationUrl: https://services-usmle-demo.fsmb.org/connect/token
          tokenUrl: https://services-usmle-demo.fsmb.org/connect/token
          scopes:
            usmle.read: Read USMLE information.
            usmle.transcript_create: Request new transcripts.
tags:
  - name: Token
  - name: Transcripts