{
  "openapi": "3.0.4",
  "info": {
    "title": "USMLE API",
    "description": "Provides access to physician USMLE information.",
    "version": "1"
  },
  "paths": {
    "/connect/token": {
      "post": {
        "tags": [
          "Token"
        ],
        "summary": "Authentication endpoint.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/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<para />\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",
        "operationId": "RequestNewTranscript",
        "parameters": [
          {
            "name": "board",
            "in": "path",
            "description": "Board code (default = 'me')",
            "required": true,
            "schema": {
              "type": "string",
              "default": "me"
            }
          },
          {
            "name": "usmleId",
            "in": "path",
            "description": "USMLE ID of the practitioner",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Accepted",
            "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",
            "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"
          }
        }
      }
    },
    "/v1/{board}/transcripts/{usmleId}/current": {
      "get": {
        "tags": [
          "Transcripts"
        ],
        "summary": "Get Current Transcript",
        "description": "Gets the current transcript for a physician.",
        "operationId": "GetCurrentTranscript",
        "parameters": [
          {
            "name": "board",
            "in": "path",
            "description": "Board code (default = 'me')",
            "required": true,
            "schema": {
              "type": "string",
              "default": "me"
            }
          },
          {
            "name": "usmleId",
            "in": "path",
            "description": "USMLE ID of the practitioner",
            "required": true,
            "schema": {
              "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/{usmleId}/files/usmle": {
      "get": {
        "tags": [
          "Transcripts"
        ],
        "summary": "Get USMLE Transcript File",
        "description": "Gets the USMLE Transcript file.",
        "operationId": "GetUsmleTranscriptFile",
        "parameters": [
          {
            "name": "board",
            "in": "path",
            "description": "Board code (default = 'me')",
            "required": true,
            "schema": {
              "type": "string",
              "default": "me"
            }
          },
          {
            "name": "usmleId",
            "in": "path",
            "description": "USMLE ID of the practitioner",
            "required": true,
            "schema": {
              "pattern": "\\d{8} ",
              "type": "string",
              "format": "USMLE ID"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "format": "byte"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string",
                  "format": "byte"
                }
              },
              "text/json": {
                "schema": {
                  "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/summary": {
      "get": {
        "tags": [
          "Transcripts"
        ],
        "summary": "Get summary of available transcripts",
        "description": "Gets a summary of available transcripts given the criteria.",
        "operationId": "GetAvailableTranscriptsSummary",
        "parameters": [
          {
            "name": "board",
            "in": "path",
            "description": "Board code (default = 'me')",
            "required": true,
            "schema": {
              "type": "string",
              "default": "me"
            }
          },
          {
            "name": "fromDate",
            "in": "query",
            "description": "Start date, inclusive",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "toDate",
            "in": "query",
            "description": "End date, inclusive",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "$orderBy",
            "in": "query",
            "description": "Field(s) to order by (optional) (default = 'sentDate')",
            "schema": {
              "type": "string",
              "default": "sentDate"
            }
          },
          {
            "name": "$offset",
            "in": "query",
            "description": "Number of items to skip (optional) (default = 0)",
            "schema": {
              "maximum": 2147483647,
              "minimum": 0,
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          },
          {
            "name": "$limit",
            "in": "query",
            "description": "Number of items to return (optional) (default = 100)",
            "schema": {
              "maximum": 2147483647,
              "minimum": 1,
              "type": "integer",
              "format": "int32",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TranscriptSummary"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TranscriptSummary"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "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"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BoardActions": {
        "type": "object",
        "properties": {
          "hasBoardActions": {
            "type": "boolean",
            "description": "Indicates if the physician has board actions."
          },
          "boardActionDescription": {
            "maxLength": 500,
            "type": "string",
            "description": "Board action description",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Board action information"
      },
      "EcfmgInformation": {
        "type": "object",
        "properties": {
          "hasPartHistory": {
            "type": "boolean",
            "description": "Indicates if ECFMG part history is available"
          },
          "partHistoryDescription": {
            "maxLength": 500,
            "type": "string",
            "description": "ECFMG part history description",
            "nullable": true
          },
          "hasLastCsa": {
            "type": "boolean",
            "description": "Indicates if ECFMG last CSA is available"
          },
          "lastCsaDescription": {
            "maxLength": 500,
            "type": "string",
            "description": "ECFMG last CSA description",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "ECFMG information"
      },
      "Exam": {
        "required": [
          "examCode",
          "examDescription"
        ],
        "type": "object",
        "properties": {
          "examCode": {
            "maxLength": 10,
            "minLength": 1,
            "type": "string",
            "description": "Exam code"
          },
          "examDescription": {
            "maxLength": 100,
            "minLength": 1,
            "type": "string",
            "description": "Exam description"
          },
          "examDate": {
            "type": "string",
            "description": "Date exam was taken",
            "format": "date-time"
          },
          "passFailStatus": {
            "maxLength": 20,
            "type": "string",
            "description": "Pass/fail status (e.g. `Pass`, `Fail`, `Undetermined`",
            "nullable": true
          },
          "score": {
            "type": "integer",
            "description": "Score",
            "format": "int32",
            "nullable": true
          },
          "minimumPassScore": {
            "type": "integer",
            "description": "Minimum passing score",
            "format": "int32",
            "nullable": true
          },
          "note": {
            "maxLength": 1000,
            "type": "string",
            "description": "Note",
            "nullable": true
          },
          "scoreAvailableDate": {
            "type": "string",
            "description": "Date score is available",
            "format": "date-time"
          },
          "hasIrregularBehavior": {
            "type": "boolean",
            "description": "Is there irregular behavior?",
            "readOnly": true
          },
          "irregularBehavior": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IrregularBehavior"
            },
            "description": "Irregular behavior",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Exam history"
      },
      "ExamSummary": {
        "required": [
          "step1",
          "step2",
          "step2CK",
          "step2CS",
          "step3"
        ],
        "type": "object",
        "properties": {
          "step1": {
            "$ref": "#/components/schemas/ExamSummaryDetail"
          },
          "step2": {
            "$ref": "#/components/schemas/ExamSummaryDetail"
          },
          "step2CS": {
            "$ref": "#/components/schemas/ExamSummaryDetail"
          },
          "step2CK": {
            "$ref": "#/components/schemas/ExamSummaryDetail"
          },
          "step3": {
            "$ref": "#/components/schemas/ExamSummaryDetail"
          }
        },
        "additionalProperties": false,
        "description": "Exam summary"
      },
      "ExamSummaryDetail": {
        "type": "object",
        "properties": {
          "lastExamDate": {
            "type": "string",
            "description": "Date exam was last taken",
            "format": "date-time",
            "nullable": true
          },
          "lastPassFailStatus": {
            "maxLength": 20,
            "type": "string",
            "description": "Pass/fail status (e.g. `Pass`, `Fail`, `Undetermined` of last exam",
            "nullable": true
          },
          "attempts": {
            "type": "integer",
            "description": "Number of attempts",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Exam summary"
      },
      "FlexInformation": {
        "type": "object",
        "properties": {
          "hasFlex": {
            "type": "boolean",
            "description": "Indicates if FLEX is available"
          },
          "flexDescription": {
            "maxLength": 500,
            "type": "string",
            "description": "FLEX description",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "FLEX information"
      },
      "IceInformation": {
        "type": "object",
        "properties": {
          "hasIce": {
            "type": "boolean",
            "description": "Indicates if ICE is available"
          },
          "iceDescription": {
            "maxLength": 500,
            "type": "string",
            "description": "ICE description",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "ICE information"
      },
      "Identification": {
        "type": "object",
        "properties": {
          "birthDate": {
            "type": "string",
            "description": "Date of birth",
            "format": "date-time",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Identity information"
      },
      "IrregularBehavior": {
        "required": [
          "description",
          "note"
        ],
        "type": "object",
        "properties": {
          "description": {
            "maxLength": 100,
            "minLength": 1,
            "type": "string",
            "description": "Irregular behavior description"
          },
          "note": {
            "maxLength": 1000,
            "minLength": 1,
            "type": "string",
            "description": "Irregular behavior note"
          }
        },
        "additionalProperties": false,
        "description": "Irregular behavior"
      },
      "Name": {
        "required": [
          "firstName",
          "lastName"
        ],
        "type": "object",
        "properties": {
          "firstName": {
            "maxLength": 50,
            "minLength": 1,
            "type": "string",
            "description": "First name"
          },
          "middleName": {
            "maxLength": 50,
            "type": "string",
            "description": "Middle name",
            "nullable": true
          },
          "lastName": {
            "maxLength": 50,
            "minLength": 1,
            "type": "string",
            "description": "Last name"
          },
          "suffix": {
            "maxLength": 4,
            "type": "string",
            "description": "Suffix",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Name of a person"
      },
      "NbmeInformation": {
        "type": "object",
        "properties": {
          "hasPartHistory": {
            "type": "boolean",
            "description": "Indicates if NBME part history is available"
          },
          "partHistoryDescription": {
            "maxLength": 500,
            "type": "string",
            "description": "NBME part history description",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "NBME information"
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": { }
      },
      "Recipient": {
        "required": [
          "name",
          "stateOrProvince"
        ],
        "type": "object",
        "properties": {
          "name": {
            "maxLength": 100,
            "minLength": 1,
            "type": "string",
            "description": "Recipient name"
          },
          "addressLines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Address lines",
            "nullable": true
          },
          "city": {
            "maxLength": 50,
            "type": "string",
            "description": "City",
            "nullable": true
          },
          "stateOrProvince": {
            "$ref": "#/components/schemas/StateOrProvince"
          },
          "postalCode": {
            "maxLength": 9,
            "type": "string",
            "description": "Postal code",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Recipient information"
      },
      "StateOrProvince": {
        "required": [
          "code",
          "description"
        ],
        "type": "object",
        "properties": {
          "code": {
            "maxLength": 3,
            "minLength": 1,
            "type": "string",
            "description": "State or province code"
          },
          "description": {
            "maxLength": 100,
            "minLength": 1,
            "type": "string",
            "description": "Description"
          },
          "countryCode": {
            "maxLength": 2,
            "type": "string",
            "description": "ISO country code",
            "nullable": true
          },
          "countryDescription": {
            "maxLength": 100,
            "type": "string",
            "description": "COuntry description",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "State or province"
      },
      "Transcript": {
        "required": [
          "boardActions",
          "ecfmg",
          "exams",
          "examSummary",
          "fid",
          "flex",
          "ice",
          "identity",
          "information",
          "legalName",
          "nbme",
          "recipient",
          "usmle",
          "usmleId"
        ],
        "type": "object",
        "properties": {
          "usmleId": {
            "maxLength": 8,
            "minLength": 1,
            "type": "string",
            "description": "USMLE ID"
          },
          "fid": {
            "maxLength": 9,
            "minLength": 1,
            "type": "string",
            "description": "FID of physician"
          },
          "recipient": {
            "$ref": "#/components/schemas/Recipient"
          },
          "information": {
            "$ref": "#/components/schemas/TranscriptInformation"
          },
          "legalName": {
            "$ref": "#/components/schemas/Name"
          },
          "identity": {
            "$ref": "#/components/schemas/Identification"
          },
          "otherNames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Name"
            },
            "description": "Other names",
            "nullable": true
          },
          "exams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Exam"
            },
            "description": "Exam history"
          },
          "examSummary": {
            "$ref": "#/components/schemas/ExamSummary"
          },
          "hasNonAdministrativeIrregularBehavior": {
            "type": "boolean",
            "description": "Is there non-administrative irregular behavior?",
            "readOnly": true
          },
          "nonAdministrativeIrregularBehavior": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IrregularBehavior"
            },
            "description": "Non-administrative Irregular behavior",
            "nullable": true
          },
          "boardActions": {
            "$ref": "#/components/schemas/BoardActions"
          },
          "nbme": {
            "$ref": "#/components/schemas/NbmeInformation"
          },
          "ecfmg": {
            "$ref": "#/components/schemas/EcfmgInformation"
          },
          "flex": {
            "$ref": "#/components/schemas/FlexInformation"
          },
          "ice": {
            "$ref": "#/components/schemas/IceInformation"
          },
          "usmle": {
            "$ref": "#/components/schemas/UsmleInformation"
          }
        },
        "additionalProperties": false,
        "description": "Physician transcript"
      },
      "TranscriptInformation": {
        "type": "object",
        "properties": {
          "hasFcvsProfile": {
            "type": "boolean",
            "description": "Determines if an FCVS profile was released",
            "readOnly": true
          },
          "fcvsReleaseDate": {
            "type": "string",
            "description": "Date the FCVS profile was released, if any",
            "format": "date-time",
            "nullable": true
          },
          "hasTranscriptRequest": {
            "type": "boolean",
            "description": "Determines if a standalone transcript request was sent",
            "readOnly": true
          },
          "transcriptSentDate": {
            "type": "string",
            "description": "Date the transcript request was sent, if any",
            "format": "date-time",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Transcript information"
      },
      "TranscriptSummary": {
        "required": [
          "examSummary",
          "fid",
          "information",
          "legalName",
          "usmleId"
        ],
        "type": "object",
        "properties": {
          "usmleId": {
            "maxLength": 8,
            "minLength": 1,
            "type": "string",
            "description": "USMLE ID"
          },
          "fid": {
            "maxLength": 9,
            "minLength": 1,
            "type": "string",
            "description": "FID of physician"
          },
          "sentDate": {
            "type": "string",
            "description": "Sent date",
            "format": "date-time",
            "readOnly": true
          },
          "information": {
            "$ref": "#/components/schemas/TranscriptInformation"
          },
          "legalName": {
            "$ref": "#/components/schemas/Name"
          },
          "examSummary": {
            "$ref": "#/components/schemas/ExamSummary"
          }
        },
        "additionalProperties": false,
        "description": "Physician transcript summary"
      },
      "UsmleInformation": {
        "type": "object",
        "properties": {
          "step2CSDescription": {
            "maxLength": 1000,
            "type": "string",
            "description": "Step2 CS description",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "USMLE information"
      }
    },
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "authorizationUrl": "https://services-usmle.fsmb.org/connect/token",
            "tokenUrl": "https://services-usmle.fsmb.org/connect/token",
            "scopes": {
              "usmle.read": "Read USMLE information.",
              "usmle.transcript_create": "Request new transcripts."
            }
          }
        }
      }
    }
  },
  "security": [
    { }
  ],
  "tags": [
    {
      "name": "Token",
      "description": "Authentication resource"
    },
    {
      "name": "Transcripts",
      "description": "Provides access to transcripts submitted to a board."
    }
  ]
}