curl -X POST "<base_url>/dpp/dbos/v2/scan" \
-H "X-AccessToken: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "string"
}'
{
"header": {
"message": "Success",
"response_code": 1
},
"body": {
"summary": {
"subject": {
"firstName": "string",
"lastName": "string",
"phone": "string",
"city": "string",
"state": "string",
"zip": "string"
},
"query": "name",
"total": 2,
"found": 1,
"notFound": 1,
"elapsedMs": 14657
},
"found": [
{
"id": "broker-name",
"name": "Broker Name",
"url": "string",
"status": "FOUND",
"optoutStrategy": "form",
"optoutUrl": "https://domain.com/remove-info.php",
"optoutEmail": "[email protected]"
}
],
"notFound": [
{
"id": "broker-name",
"name": "Broker Name",
"status": "NOT_FOUND"
}
]
}
}
Broker Scan
Instant People Search
A one-off lookup that runs a broker probe and returns a minimal response split into two arrays.
POST
/
dpp
/
dbos
/
v2
/
scan
curl -X POST "<base_url>/dpp/dbos/v2/scan" \
-H "X-AccessToken: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "string"
}'
{
"header": {
"message": "Success",
"response_code": 1
},
"body": {
"summary": {
"subject": {
"firstName": "string",
"lastName": "string",
"phone": "string",
"city": "string",
"state": "string",
"zip": "string"
},
"query": "name",
"total": 2,
"found": 1,
"notFound": 1,
"elapsedMs": 14657
},
"found": [
{
"id": "broker-name",
"name": "Broker Name",
"url": "string",
"status": "FOUND",
"optoutStrategy": "form",
"optoutUrl": "https://domain.com/remove-info.php",
"optoutEmail": "[email protected]"
}
],
"notFound": [
{
"id": "broker-name",
"name": "Broker Name",
"status": "NOT_FOUND"
}
]
}
}
A one-off lookup that runs a broker probe and returns a minimal response split into two arrays. found[] holds brokers that returned FOUND, each with optoutStrategy (form, email, none, or null when the broker is not yet in the opt-out registry), plus optoutUrl when the strategy is form and optoutEmail when it is email. notFound[] holds everything else, including inconclusive results (UNKNOWN, CF_CHALLENGE, ERROR or dead-domain). Input: phone for a reverse-phone scan, or firstName + lastName (optionally city, state, zip) for a name scan; at least one is required. Filters: country (ISO-2) and region (US or EU) are optional and country wins when both are set; neither selects all brokers, region EU selects every non-US broker, and an unknown region applies no filter. brokerIds narrows to specific brokers after country/region filtering. FOUND means the name (or phone digits) appeared in an HTTP 2xx page of at least 800 bytes at the broker’s search URL. Unrelated to POST /dpp/dbos/v2/users/{profileId}/initiate-scan, which starts a user’s full broker scan.
See Errors for the response envelope and the full list of codes.
- URL:
/dpp/dbos/v2/scan - Full URL:
<base_url>/dpp/dbos/v2/scan - Request Method: POST
Authentication
Send the Access Token in theX-AccessToken request header on every authenticated call:
X-AccessToken: YOUR_ACCESS_TOKEN
Request Body
Provide phone (reverse-phone scan) and/or firstName + lastName (name scan).string
Required together with lastName for a name scan.
string
Required together with firstName for a name scan.
string
Optional narrowing for a name scan.
string
US state. Optional narrowing for a name scan.
string
Optional narrowing.
string
10-digit phone number for a reverse-phone scan.
string
Optional ISO-2 filter. US selects US brokers only; an EU code (DE, FR, IT, NL, …) selects that country only. Wins over region.
string
Optional region filter. Ignored when country is supplied; unknown values apply no filter.
string[]
Optional list of broker ids to probe, applied after country/region filtering.
Sample Request
cURL
curl -X POST "<base_url>/dpp/dbos/v2/scan" \
-H "X-AccessToken: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "string"
}'
curl -X POST "<base_url>/dpp/dbos/v2/scan" \
-H "X-AccessToken: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "string"
}'
Response
object
object
Show body
Show body
object
object[]
Sample Response
Success
{
"header": {
"message": "Success",
"response_code": 1
},
"body": {
"summary": {
"subject": {
"firstName": "string",
"lastName": "string",
"phone": "string",
"city": "string",
"state": "string",
"zip": "string"
},
"query": "name",
"total": 2,
"found": 1,
"notFound": 1,
"elapsedMs": 14657
},
"found": [
{
"id": "broker-name",
"name": "Broker Name",
"url": "string",
"status": "FOUND",
"optoutStrategy": "form",
"optoutUrl": "https://domain.com/remove-info.php",
"optoutEmail": "[email protected]"
}
],
"notFound": [
{
"id": "broker-name",
"name": "Broker Name",
"status": "NOT_FOUND"
}
]
}
}
{
"header": {
"message": "Success",
"response_code": 1
},
"body": {
"summary": {
"subject": {
"firstName": "string",
"lastName": "string",
"phone": "string",
"city": "string",
"state": "string",
"zip": "string"
},
"query": "name",
"total": 2,
"found": 1,
"notFound": 1,
"elapsedMs": 14657
},
"found": [
{
"id": "broker-name",
"name": "Broker Name",
"url": "string",
"status": "FOUND",
"optoutStrategy": "form",
"optoutUrl": "https://domain.com/remove-info.php",
"optoutEmail": "[email protected]"
}
],
"notFound": [
{
"id": "broker-name",
"name": "Broker Name",
"status": "NOT_FOUND"
}
]
}
}
Status Codes
| Status | Meaning |
|---|---|
200 | Scan completed. |
400 | 11000: neither phone nor both firstName and lastName sent. 10002: a field fails validation. |
502 | 11001: the broker scan service returned an error or did not answer in time. |
503 | 11001: the broker scan service is not configured. |
Error codes
Returned inheader.response_code when the request fails.
| Code | Message |
|---|---|
10002 | A field fails validation. |
10006 | {invalid JSON body error} / Validation failed (numeric string is expected) |
11000 | Neither phone nor both firstName and lastName sent. |
11001 | The broker scan service returned an error or did not answer in time. |