Principal Detailed Search

post

This endpoint allows you to submit a principal (individual) for detailed background verification.

Current Capabilities: This endpoint currently supports the following data sources:

  • Bankruptcies: Individual bankruptcy records

  • Liens: Tax and other lien records

  • Judgements: Civil judgment records

  • Watchlists: Sanctions and watchlist screening

  • Healthcare Professional Verification: Medical license verification for healthcare professionals

  • Home Services License Verification: Professional license verification for contractors and home service professionals

Principal Categories:

  • healthcare: For medical professionals (doctors, nurses, etc.). License verification is supported.

  • homeServices: For home service professionals (contractors, etc.). License verification is supported.

  • other: For all other principals. License verification is not supported for this category.

License Verification: License verification is now fully supported for healthcare and homeServices categories:

Healthcare Professionals:

  • Set enhanced_license_search to true to search our database for additional licenses beyond those provided

  • If enhanced_license_search is true but no licenses are provided, the system will attempt to find and verify all licenses for the matched healthcare professional

  • If enhanced_license_search is true AND specific licenses are provided, the system will verify BOTH the provided licenses AND all licenses found in our database (duplicates are automatically removed)

  • If enhanced_license_search is false AND specific licenses are provided, the system will verify ONLY the provided licenses (no NPI database lookup)

  • Each license requires licensee_state (2-character state code) and licensee_id (license number)

  • For healthcare professionals, you may also provide an npi_id to help with matching

Home Services Professionals:

  • The enhanced_license_search field is ignored for homeServices professionals

  • License verification is triggered by the presence of licenses in the licenses array

  • Each license requires licensee_state (2-character state code) and licensee_id (license number)

Required Fields:

  • first_name, last_name, callback_url, merchant_id, principal_category

  • run_license_verification: Boolean - Whether to run license verification searches

  • run_litigation: Boolean - Whether to run litigation searches

  • run_bljs: Boolean - Whether to run bankruptcy, lien, and judgment searches

  • run_adverse_media: Boolean - Whether to run adverse media searches

Optional Fields for License Verification:

  • enhanced_license_search: Boolean indicating whether to search NPI database for additional licenses (healthcare only)

  • licenses: Array of license objects with licensee_state and licensee_id

Response: This endpoint returns a request ID that can be used to check the status or retrieve results of the principal verification process. The actual detailed report will be sent to the provided callback URL when processing is complete.

Callback Response: When processing is complete, the callback URL will receive a POST request with the same response format as the Seller Report endpoint. This includes all the detailed background verification results for the principal.

Principals Structure Updates: The principals field in the response has been updated for this new process. principals is a list of unique principals associated with the merchant. Each unique principal record contains a source_principals key, which is a list of source-level principal records.

Each item in the source_principals list represents a principal found from a specific data source. If a principal was discovered through a bankruptcy, lien, or judgment (BLJ) search, the corresponding blj_data field will contain all the necessary information about that principal from that source.

Processing Time: Typical processing time is 5-10 minutes depending on the data sources being searched.

Authorizations
AuthorizationstringRequired
Header parameters
LenderIdstringRequired

Lender ID provided by Verdata

Body
first_namestring · min: 1Required
middle_namestringOptional
last_namestring · min: 1Required
suffixstringOptional
addr1stringOptional
addr2stringOptional
citystringOptional
statestringOptional
zip5stringOptional
zip4stringOptional
dpcstringOptional
dobstring · dateOptional
ssnstringOptional
npi_idstringOptional
phonestringOptional
emailstringOptional
callback_urlstring · min: 1Required
merchant_idstring · uuidRequired
lender_idstringOptional
principal_categorystring · min: 1Required

Must be one of: healthcare, homeServices, other

enhanced_license_searchbooleanOptional

For healthcare only: true=searches our internal database for additional licenses, false=verify only provided licenses

run_license_verificationbooleanRequired

Whether to run license verification searches

run_litigationbooleanRequired

Whether to run litigation searches

run_bljsbooleanRequired

Whether to run bankruptcy, lien, and judgment searches

run_adverse_mediabooleanRequired

Whether to run adverse media searches

Responses
200

Seller Detailed Report

application/json
post
/principal-detailed
POST /external/api/v1/principal-detailed HTTP/1.1
Host: api.myverdata.com
Authorization: YOUR_API_KEY
LenderId: text
Content-Type: application/json
Accept: */*
Content-Length: 563

{
  "first_name": "text",
  "middle_name": "text",
  "last_name": "text",
  "suffix": "text",
  "addr1": "text",
  "addr2": "text",
  "city": "text",
  "state": "text",
  "zip5": "text",
  "zip4": "text",
  "dpc": "text",
  "dob": "2025-12-06",
  "ssn": "text",
  "npi_id": "text",
  "phone": "text",
  "email": "text",
  "callback_url": "text",
  "merchant_id": "123e4567-e89b-12d3-a456-426614174000",
  "lender_id": "text",
  "principal_category": "text",
  "enhanced_license_search": true,
  "licenses": [
    {
      "licensee_state": "text",
      "licensee_id": "text"
    }
  ],
  "run_license_verification": true,
  "run_litigation": true,
  "run_bljs": true,
  "run_adverse_media": true
}
200

Seller Detailed Report

{
  "status": "text",
  "request_id": "123e4567-e89b-12d3-a456-426614174000"
}
get

Check the status of a Principal Detailed Search request by passing in principal_request_id.

Authorizations
AuthorizationstringRequired
Path parameters
principal_request_idanyRequired
Header parameters
LenderIdstringRequired

Lender ID provided by Verdata

Responses
200

Principal Detail Request Status

application/json
get
/principal-detailed/{principal_request_id}
GET /external/api/v1/principal-detailed/{principal_request_id} HTTP/1.1
Host: api.myverdata.com
Authorization: YOUR_API_KEY
LenderId: text
Accept: */*
200

Principal Detail Request Status

{
  "principal_request_id": "text",
  "status": "text",
  "created_at": "2025-12-06T03:54:32.239Z",
  "updated_at": "2025-12-06T03:54:32.239Z"
}
PreviousOn Demand MerchantNextScorecard Update

Last updated