{
  "openapi": "3.0.3",
  "info": {
    "title": "NBPAS API",
    "version": "1.3.0",
    "description": "Look up a physician's certification with the National Board of Physicians and Surgeons (NBPAS) by NPI. Human-readable documentation: https://api.nbpas.org/docs",
    "contact": {
      "name": "NBPAS",
      "email": "info@nbpas.org"
    }
  },
  "servers": [
    {
      "url": "https://api.nbpas.org/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/applications": {
      "get": {
        "operationId": "getApplicationsByNpi",
        "summary": "Look up a physician by NPI",
        "parameters": [
          {
            "name": "npi",
            "in": "query",
            "required": true,
            "description": "The physician's 10-digit National Provider Identifier.",
            "schema": {
              "type": "string",
              "example": "1234567893"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup succeeded. `records` is empty when no physician matches.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "records"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "success"
                      ]
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Record"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The `npi` query parameter is missing.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No token, or the token is unknown or deactivated.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The request was made over plain HTTP.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error on our side.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/applications/bulk": {
      "get": {
        "operationId": "getApplicationsBulk",
        "summary": "List physicians by status, in pages",
        "description": "Requires bulk access to be enabled for the access token. Each physician appears once, with their current status. Follow `nextCursor` until it is null; a page can hold fewer records than `limit` (even none) while `nextCursor` is still set. With `updatedSince` and a `status`, physicians whose status changed to a value outside the filter are not included. A removed specialty or subspecialty is only detected for about 14 days after it happens.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Certification status filter. One value, or several separated by commas. Omit for all statuses.",
            "schema": {
              "type": "string",
              "example": "Active,Expired"
            }
          },
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "description": "Only physicians whose data changed at or after this time: their profile, any of their applications, or the specialties on those applications. Each physician is returned as their full current record. A date (YYYY-MM-DD, midnight UTC) or an ISO 8601 date-time.",
            "schema": {
              "type": "string",
              "example": "2026-11-01"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum physicians per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page. Omit for the first page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of physicians.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "records",
                    "nextCursor"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "success"
                      ]
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Record"
                      }
                    },
                    "removed": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Only present when `updatedSince` is used. The `nbpasId`s of physicians whose data changed but who have no certification or application to report (for example, their only application was canceled, or they have only started an application). Many were never returned as records. Can appear on any page, including one with no records."
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Pass as `cursor` to get the next page. Null when there are no more pages."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A query parameter has an invalid value.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No token, or the token is unknown or deactivated.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The token is not enabled for bulk access, or the request was made over plain HTTP.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error on our side.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Access token issued by NBPAS."
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "description": "Requests allowed in the current window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests left in the current window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer"
        }
      },
      "X-Request-Id": {
        "description": "Unique ID for this request. Quote it when contacting support.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Record": {
        "type": "object",
        "properties": {
          "nbpasId": {
            "type": "string",
            "description": "The physician's NBPAS ID."
          },
          "firstName": {
            "type": "string"
          },
          "middleName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string"
          },
          "credentials": {
            "type": "string",
            "nullable": true,
            "enum": [
              "M.D.",
              "D.O.",
              "PhD",
              "M.D., PhD",
              "D.O., PhD",
              null
            ]
          },
          "initialCertificationDate": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "npi": {
            "type": "string"
          },
          "specialties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Specialty"
            }
          },
          "subspecialties": {
            "type": "array",
            "description": "Subspecialties not linked to any specialty above. Usually empty.",
            "items": {
              "$ref": "#/components/schemas/Subspecialty"
            }
          },
          "renewalInProgress": {
            "type": "boolean"
          },
          "applicationId": {
            "type": "string",
            "description": "ID of the application the certification details come from."
          },
          "certificationStatus": {
            "type": "string",
            "enum": [
              "Active",
              "Submitted",
              "In Progress",
              "On Hold",
              "Expired",
              "Retired"
            ]
          },
          "expirationDate": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "printCertificationUrl": {
            "type": "string",
            "format": "uri"
          },
          "verificationUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Specialty": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "ABMS",
              "AOA"
            ]
          },
          "needHospitalPrivileges": {
            "type": "boolean"
          },
          "subspecialties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Subspecialty"
            }
          }
        }
      },
      "Subspecialty": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "needHospitalPrivileges": {
            "type": "boolean"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "fail",
              "error"
            ],
            "description": "`fail` for 4xx, `error` for 5xx."
          },
          "success": {
            "type": "string",
            "enum": [
              "fail",
              "error"
            ],
            "description": "Same as `status`; kept for older integrations."
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        }
      }
    }
  }
}
