NBPAS API Documentation
The NBPAS API lets approved partners check a physician's certification with the National Board of Physicians and Surgeons (NBPAS) using their NPI.
Base URL
https://api.nbpas.org/v1
Every request must use HTTPS. Requests over plain HTTP are rejected with 403. Every response is JSON (application/json).
A machine-readable OpenAPI 3.0 specification is available if you want to generate a client library.
Authentication
NBPAS issues each partner its own access token. Send it as a Bearer token in the Authorization header on every request:
Authorization: Bearer YOUR_ACCESS_TOKEN
A request with no token, or with a token that is unknown or has been deactivated, gets a 401 response. Keep your token secret and only use it from your servers, never in browser or mobile app code. If you think your token has been exposed, contact info@nbpas.org to have it replaced.
Rate limits
| Limit | Applies to |
|---|---|
| 60 requests per minute | Each access token, from any IP address. NPI lookups and bulk pages share this limit. |
| 20 failed authentication attempts per 15 minutes | Each IP address. Only 401 responses count. |
Every response from /applications and /applications/bulk includes these headers:
| Header | Description |
|---|---|
RateLimit-Limit | Requests allowed in the current window. |
RateLimit-Remaining | Requests left in the current window. |
RateLimit-Reset | Seconds until the window resets. |
Going over a limit returns 429 Too Many Requests. Wait until RateLimit-Reset seconds have passed, then retry. If you need a higher limit, contact info@nbpas.org.
Look up a physician by NPI
Returns the NBPAS certification details for the physician with the given National Provider Identifier.
Query parameters
| Name | Type | Description |
|---|---|---|
npirequired | string | The physician's 10-digit National Provider Identifier. |
Example request
curl https://api.nbpas.org/v1/applications?npi=1234567893 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response
200 OK
{
"status": "success",
"records": [
{
"nbpasId": "123456",
"firstName": "Jane",
"middleName": "A",
"lastName": "Doe",
"credentials": "M.D.",
"initialCertificationDate": "2019-06-02",
"npi": "1234567893",
"specialties": [
{
"id": "a045e00000ABCDEFGH",
"name": "Internal Medicine",
"type": "ABMS",
"needHospitalPrivileges": false,
"subspecialties": [
{ "name": "Cardiovascular Disease", "needHospitalPrivileges": false },
{ "name": "Interventional Cardiology", "needHospitalPrivileges": true }
]
}
],
"subspecialties": [],
"renewalInProgress": false,
"applicationId": "006XXXXXXXXXXXXXXX",
"certificationStatus": "Active",
"expirationDate": "2026-06-30",
"printCertificationUrl": "https://nbpas.org/pages/print-certification?opportunity_id=006XXXXXXXXXXXXXXX",
"verificationUrl": "https://nbpas.org/pages/verify-individual?opportunity_id=006XXXXXXXXXXXXXXX"
}
]
}
records is always an array. If no physician has the NPI you sent, you get 200 OK with an empty array ("records": []). In rare cases one NPI matches more than one physician record, and you get more than one entry. A physician whose only applications are unsubmitted or canceled is not included.
List by status
Returns physicians in pages, optionally filtered by certification status or by when their records last changed. Use it to fetch every physician with a given status, or to keep your own copy of the list up to date.
Each physician appears once, with their current status, worked out the same way as the NPI lookup. For example, a physician who renewed comes back as Active, not Expired, and status=Expired only returns physicians whose certification has ended and who haven't renewed. Older applications are never returned.
Bulk access must be enabled for your token. Tokens without it get 403. To request access, contact info@nbpas.org.
Query parameters
| Name | Type | Description |
|---|---|---|
status | string | Only return physicians with this certification status. To ask for several, separate them with commas, for example Active,Expired. Leave it out to get every status. |
updatedSince | string | Only return physicians whose data changed on or after this time: their profile, any of their applications, or the specialties on those applications. Each physician comes back as their full current record. Use a date (2026-11-01, which means midnight UTC) or an ISO 8601 date-time (2026-11-01T14:30:00Z). |
limit | integer | Maximum physicians per page, from 1 to 200. The default is 100. |
cursor | string | The nextCursor value from the previous page. Leave it out for the first page. |
Example request
curl "https://api.nbpas.org/v1/applications/bulk?status=Active&limit=200" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response
200 OK
{
"status": "success",
"records": [
{ "nbpasId": "123456", "firstName": "Jane", "lastName": "Doe", "certificationStatus": "Active", ... },
...
],
"nextCursor": "MDAzNWUwMDAwMEFCQ0RFRkdI"
}
Each entry in records is the same record object the NPI lookup returns.
Requests with updatedSince also include removed, a list of nbpasIds. These are 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 (Incomplete applications are never returned). Many of them were never returned as records. The list is often empty, and it can appear on any page, including a page with no records.
{
"status": "success",
"records": [ ... ],
"removed": ["654321"],
"nextCursor": null
}
Pagination
To get the next page, repeat the same request with cursor set to the nextCursor you received. Stop when nextCursor is null.
cursor = null
do {
page = GET /v1/applications/bulk?status=Active&limit=200&cursor={cursor}
save(page.records)
cursor = page.nextCursor
} while (cursor != null)
- A cursor marks a position in the results of the request it came from, so it belongs with that request's other parameters.
- A page can contain fewer records than
limit, or none at all, whilenextCursoris still set. The results end only whennextCursorisnull. - Cursors don't expire. Each physician appears at most once per run, even if data changes while you're paging. Anything that changes during a run is returned by a later
updatedSincerequest that covers the time of the change. - Each page counts as one request toward your rate limit. At 200 per page, that's up to 12,000 physicians a minute.
Tracking changes
updatedSincereturns every physician whose data changed on or after that time, as their full current record, plus theremovedlist.- Combined with
status, it only returns changed physicians whose current status matches. A physician whose status changed to a value outside the filter, for example fromActivetoExpired, is not included. Withoutstatus, every changed physician is included, whatever their status. - Any edit to a physician's data counts as a change, so a physician can be returned even if none of the fields in the response changed.
- Most changes can be found with any
updatedSincevalue. The exception is a specialty or subspecialty removed from an application: that change is only detected for about 14 days after it happens.
Record object
Each entry in records is one physician, in both the NPI lookup and bulk responses.
| Field | Type | Description |
|---|---|---|
nbpasId | string | The physician's NBPAS ID. |
firstName | string | The physician's first name. |
middleName | string | null | Middle name or initial, if we have one. |
lastName | string | The physician's last name. |
credentials | string | null | One of M.D., D.O., PhD, M.D., PhD, D.O., PhD. Can be null if not on file. |
initialCertificationDate | string (date) | The date the physician was first certified by NBPAS, as YYYY-MM-DD. |
npi | string | The physician's National Provider Identifier. |
specialties | array | The specialties covered by the certification. See Specialty object. |
subspecialties | array | Subspecialties that aren't linked to any of the specialties above. Usually empty, because most subspecialties appear inside their parent specialty. See Subspecialty object. |
renewalInProgress | boolean | true if the physician holds an active certification and has also submitted a renewal that is still being processed. |
applicationId | string | The unique ID of the application this record's certification details come from. |
certificationStatus | string | The status of the certification. See Certification status. |
expirationDate | string (date) | The date the certification ends, as YYYY-MM-DD. |
printCertificationUrl | string (URL) | A link to the physician's printable certificate on nbpas.org. |
verificationUrl | string (URL) | A link to the physician's public verification page on nbpas.org, where anyone can confirm the certification. |
Renewals: when renewalInProgress is true, applicationId, certificationStatus, expirationDate, specialties and both URLs describe the current active certification, not the pending renewal. Otherwise they describe the physician's most recent application.
Specialty object
| Field | Type | Description |
|---|---|---|
id | string | NBPAS's identifier for this specialty on the physician's certification. |
name | string | The name of the specialty, for example Internal Medicine. |
type | string | The board type: ABMS or AOA. |
needHospitalPrivileges | boolean | true if NBPAS requires hospital privileges for this specialty. |
subspecialties | array | The subspecialties under this specialty. See Subspecialty object. |
Subspecialty object
| Field | Type | Description |
|---|---|---|
name | string | The name of the subspecialty, for example Interventional Cardiology. |
needHospitalPrivileges | boolean | true if NBPAS requires hospital privileges for this subspecialty. |
Certification status
certificationStatus is always one of these values:
| Value | Meaning |
|---|---|
Active | Currently certified by NBPAS. |
Submitted | Application submitted and waiting for review. |
In Progress | Application under review by NBPAS. |
On Hold | Application on hold while NBPAS waits for information from the physician. |
Expired | The certification has ended. |
Retired | The physician has retired. |
Only Active means the physician is currently certified.
Errors
Errors use standard HTTP status codes. The body is JSON:
{
"status": "fail",
"success": "fail",
"message": "Invalid Access Token",
"requestId": "01306dbb-7a39-3230-5686-0f5047a16d10"
}
statusis"fail"for4xxerrors and"error"for5xxerrors.successalways has the same value asstatus. It's kept for older integrations;statusis the main field.requestIdidentifies the request. It's also sent in theX-Request-Idheader on every response. Include it when you contact support.
| Status | Message | Cause |
|---|---|---|
400 | Invalid parameters | The npi query parameter is missing or empty. |
400 | Invalid status… / Invalid updatedSince… / Invalid limit… / Invalid cursor. | A bulk parameter has an invalid value. The message explains what's accepted. |
401 | Invalid Authentication | No Authorization: Bearer header was sent. |
401 | Invalid Access Token | The token is unknown or has been deactivated. |
403 | This access token is not enabled for bulk access. | Your token can do NPI lookups but not bulk lookups. Contact info@nbpas.org. |
403 | HTTPS is required | The request used http://. Use https://, and treat the token you sent as exposed. |
404 | Can't find <path> | The URL doesn't match an endpoint. Check that it includes /v1. |
429 | Rate limit exceeded… / Too many failed authentication attempts… | See Rate limits. |
500 | Something went wrong… | An unexpected error on our side. Retry later. If it keeps happening, contact info@nbpas.org with the requestId. |
Changelog
1.3 · November 2026
- Added the list by status endpoint,
GET /applications/bulk, withstatusandupdatedSincefilters and cursor pagination. WithupdatedSince, the response also listsremovedphysicians.
1.2 · November 2026
- Added rate limits and
RateLimit-*response headers. - Plain-HTTP requests are now rejected with
403. - Error responses now include
status(the same value assuccess) andrequestId. Every response carries anX-Request-Idheader. 500responses no longer include internal error details.- Published an OpenAPI specification.
1.1 · November 2026
- Added the
nbpasId,applicationIdandverificationUrlfields. - Documented the response envelope: results come in a
recordsarray with astatusfield. - Added the
idand nestedsubspecialtiesfields to the specialty object, and explained when the top-levelsubspecialtiesarray is used. - Removed
typefrom the subspecialty object. The API has never returned it. - Added the
Retiredcertification status. - Noted that
credentialscan benull. - Added the error reference.
1.0
- Initial release.