The article explains how to submit license verification requests via an API call, requiring stateCode and professionCode for each license, with optional fields to improve matching. Up to 500 licenses can be submitted per request. Missing required fields cause a FAILED response with an error code. ClientMetadata and customProperties allow tracking by echoing user data in results. Verification results are returned asynchronously via webhooks. Sample codes for states and professions are listed in a reference document.
What a request asks
Each request submits a list of licenses to verify. For every license you must include two things; everything else is optional search criteria that helps match the right record.
-
State code (
stateCode) — the issuing state or body. -
Profession code (
professionCode) — the profession being verified.
You can submit up to 500 licenses in a single request.
Authorization header.{
"clientMetadata": { "mySampleID": "ID-0012044-SAMPLE" }, // optional, for your tracking
"licenses": [
{
"licenseNumber": "RN1234567",
"professionCode": "RN",
"stateCode": "FL",
"certState": "FL",
"customProperties": {
"dateOfBirth": "19850101",
"socialSecurityNumber": "123456789"
"zipCode": "12345"
"firstName": "Jordan",
"middleName": "Malcom",
"lastName": "Rivera",
}
]
}
Field reference State & Profession Codes
| Field | Required | What it is |
|---|---|---|
| clientMetadata | No | Optional information to be controlled by the sender. Anything inside this object will be echoed back to the customer. |
| licenses | Yes | For a license verification, at least the required fields must be sent, depending on the board other information flagged as conditional is needed. If a field is not required, it must not be added in the request. — up to 500 per request. |
| licenseNumber | Usually | The specific license number to be verified. The format can vary between profession code and state. |
| professionCode | Yes | The profession code designating the type of license. List of permitted codes. See here for additional information: State & Profession Codes |
| stateCode | Yes | The 2-character state code for the license when stateCode is set to 'CERT'. Note, if there is no certState associated, then do not include certState in the request body. |
| certState | Optional | Certification state, where relevant. |
| customProperties | No | Free-form per-license values, echoed back in that license’s result. Example: "customFields": { "employeeHR_ID": "ABC1234" }, |
| dateOfBirth | Conditional |
This field can be required by some boards. Date of birth of the license owner in the format Year + Month + Day. Example: |
| socialSecurityNumber | Conditional | This 9-digit field can be required by some boards |
| zipCode | Optional | |
| firstName | Conditional | Helps match; required by some sources. |
| middleName | Optional | |
| lastName | Conditional | Helps match; required by some sources. |
Search criteria
Every primary source uses a slightly different mix of details to find an accurate match. Most sources need only a license number alongside the state and profession codes; some require more — typically first name, last name, and date of birth.
FAILED with the code err_missing_val_flds and a message listing what’s required. Add the missing fields and resend just that license.
{
"code": "err_missing_val_flds",
"message": "The following values are required: firstName, lastName, dateOfBirth",
"status": "FAILED",
"input": {
"stateCode": "CERT",
"professionCode": "CRT",
"licenseNumber": "NBRC12345"
}
}Linking results back to your system
Verification ignores clientMetadata and customProperties entirely — but echoes them back untouched on every result. That makes them the place to stash your own identifiers so you can match a result to the right person or workflow on your side. A common shape carries a correlation ID and who to notify:
{
"corelationID": "REQ-2026-00184",
"employeeEmail": "[email protected]",
"employeeName": "Jordan Rivera"
}Put batch-wide values in clientMetadata and per-license values in customProperties — both come back exactly as you sent them.
How results come back
Verification runs asynchronously — you don’t wait on the response. Results arrive through webhooks: a licenseVerified event for each credential, and a licenseVerificationBatchFinished event once the whole batch is done.