Batch Inquiries

List Batches

get

List batches with aggregated status, scoped to your organization.

Returns a paginated list of batches. Use limit and offset to page through results.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT token from Cognito, or lender API key (vd__). API keys can be obtained via GET /users/me/api-key.

Query parameters

limitinteger · max: 500OptionalDefault: 100

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

Response for listing batches with pagination

totalintegerRequired

limitintegerRequired

offsetintegerRequired

422

Validation Error

application/json

get

/v1/batch-inquiries/

HTTPcURLJavaScriptPython

GET /v1/batch-inquiries/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "batches": [
    {
      "batchId": "123e4567-e89b-12d3-a456-426614174000",
      "batchName": "text",
      "operationType": "DISCOVERY",
      "status": "PENDING",
      "total": 1,
      "planning": 1,
      "running": 1,
      "completed": 1,
      "partialSuccess": 1,
      "failed": 1,
      "progressPercentage": 1,
      "createdAt": "2026-03-25T13:20:55.314Z",
      "phaseProgress": {
        "currentPhase": "text",
        "processesTotal": 1,
        "processesCompleted": 1,
        "processesRunning": 1,
        "processesPending": 1,
        "phaseCounts": {
          "ANY_ADDITIONAL_PROPERTY": {
            "total": 1,
            "completed": 1,
            "succeeded": 1,
            "running": 1,
            "pending": 1
          }
        }
      },
      "sourceRecordTotals": {
        "business": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "principal": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "totalRecords": 1
      },
      "timingSummary": {
        "oldestQueued": {
          "inquiryId": "123e4567-e89b-12d3-a456-426614174000",
          "businessName": "text",
          "createdAt": "2026-03-25T13:20:55.314Z",
          "startedAt": "2026-03-25T13:20:55.314Z",
          "completedAt": "2026-03-25T13:20:55.314Z",
          "durationMs": 1
        },
        "longestRunning": {
          "inquiryId": "123e4567-e89b-12d3-a456-426614174000",
          "businessName": "text",
          "createdAt": "2026-03-25T13:20:55.314Z",
          "startedAt": "2026-03-25T13:20:55.314Z",
          "completedAt": "2026-03-25T13:20:55.314Z",
          "durationMs": 1
        },
        "medianStartDelayMs": 1
      }
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Submit Batch Inquiry

post

Submit a batch of inquiries for processing.

Accepts up to the configured lender batch max in a single request (250 by default). Each item follows the same field requirements as POST /v1/inquiries/ (see that endpoint for field details).

Recommended workflow:

1. Submit the batch via this endpoint.

2. Poll GET /v1/batch-inquiries/{batch_id} every 30 seconds to monitor overall progress.

3. Once complete, retrieve individual results via GET /v1/batch-inquiries/{batch_id}/inquiries.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT token from Cognito, or lender API key (vd__). API keys can be obtained via GET /users/me/api-key.

Body

application/json

Request model for submitting a batch of inquiries

namestringRequired

Responses

200

Successful Response

application/json

Response after submitting a batch of inquiries

batchIdstring · uuidRequired

batchNamestringRequired

totalintegerRequired

messagestringRequired

422

Validation Error

application/json

post

/v1/batch-inquiries/

HTTPcURLJavaScriptPython

POST /v1/batch-inquiries/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 777

{
  "name": "text",
  "items": [
    {
      "businessName": "text",
      "businessCity": "text",
      "businessState": "text",
      "businessDba": "text",
      "businessEin": "text",
      "businessAddressLine1": "text",
      "businessAddressLine2": "text",
      "businessZip": "text",
      "businessPhone": "text",
      "businessEmail": "text",
      "businessDomain": "text",
      "businessSosId": "text",
      "principals": [
        {
          "firstName": "text",
          "middleName": "text",
          "lastName": "text",
          "suffix": "text",
          "dob": "2026-03-25",
          "npi": "text",
          "phone": "text",
          "email": "text",
          "addr1": "text",
          "addr2": "text",
          "city": "text",
          "state": "text",
          "zip5": "text",
          "principalType": "UNKNOWN",
          "ownershipPercentage": 1,
          "searchNpi": false
        }
      ],
      "licenses": [
        {
          "licenseName": "text",
          "licenseId": "text",
          "licenseState": "text",
          "licenseCategory": "homeServices",
          "licenseSubcategory": "text"
        }
      ],
      "tags": [
        "text"
      ],
      "externalId": "text"
    }
  ]
}

{
  "batchId": "123e4567-e89b-12d3-a456-426614174000",
  "batchName": "text",
  "total": 1,
  "message": "text"
}

Get Batch Status

get

Get status summary for a batch.

Returns progress_percentage and per-status counts (e.g., how many inquiries are COMPLETED, RUNNING, FAILED, etc.). Poll this endpoint every 30 seconds to monitor batch progress.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT token from Cognito, or lender API key (vd__). API keys can be obtained via GET /users/me/api-key.

Path parameters

batch_idstringRequired

Responses

200

Successful Response

application/json

Status summary for a batch of inquiries

batchIdstring · uuidRequired

batchNameany ofRequired

stringOptional

or

nullOptional

operationTypeany ofOptional

string · enumOptionalPossible values:

or

nullOptional

statusany ofOptional

string · enumOptionalPossible values:

or

nullOptional

totalintegerRequired

planningintegerRequired

runningintegerRequired

completedintegerRequired

partialSuccessintegerRequired

failedintegerRequired

progressPercentagenumberRequired

createdAtstring · date-timeRequired

phaseProgressany ofOptional

or

nullOptional

sourceRecordTotalsany ofOptional

or

nullOptional

timingSummaryany ofOptional

or

nullOptional

422

Validation Error

application/json

get

/v1/batch-inquiries/{batch_id}

HTTPcURLJavaScriptPython

GET /v1/batch-inquiries/{batch_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "batchId": "123e4567-e89b-12d3-a456-426614174000",
  "batchName": "text",
  "operationType": "DISCOVERY",
  "status": "PENDING",
  "total": 1,
  "planning": 1,
  "running": 1,
  "completed": 1,
  "partialSuccess": 1,
  "failed": 1,
  "progressPercentage": 1,
  "createdAt": "2026-03-25T13:20:55.314Z",
  "phaseProgress": {
    "currentPhase": "text",
    "processesTotal": 1,
    "processesCompleted": 1,
    "processesRunning": 1,
    "processesPending": 1,
    "phaseCounts": {
      "ANY_ADDITIONAL_PROPERTY": {
        "total": 1,
        "completed": 1,
        "succeeded": 1,
        "running": 1,
        "pending": 1
      }
    }
  },
  "sourceRecordTotals": {
    "business": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "principal": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "totalRecords": 1
  },
  "timingSummary": {
    "oldestQueued": {
      "inquiryId": "123e4567-e89b-12d3-a456-426614174000",
      "businessName": "text",
      "createdAt": "2026-03-25T13:20:55.314Z",
      "startedAt": "2026-03-25T13:20:55.314Z",
      "completedAt": "2026-03-25T13:20:55.314Z",
      "durationMs": 1
    },
    "longestRunning": {
      "inquiryId": "123e4567-e89b-12d3-a456-426614174000",
      "businessName": "text",
      "createdAt": "2026-03-25T13:20:55.314Z",
      "startedAt": "2026-03-25T13:20:55.314Z",
      "completedAt": "2026-03-25T13:20:55.314Z",
      "durationMs": 1
    },
    "medianStartDelayMs": 1
  }
}

Get Batch Inquiries

get

Get individual inquiry results from a batch with pagination.

Use limit and offset to page through the inquiries in this batch. Each item includes the inquiry status, progress, and source record count.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT token from Cognito, or lender API key (vd__). API keys can be obtained via GET /users/me/api-key.

Path parameters

batch_idstringRequired

Query parameters

limitinteger · max: 500OptionalDefault: 100

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

Response for listing inquiries in a batch

batchIdstring · uuidRequired

totalintegerRequired

limitintegerRequired

offsetintegerRequired

422

Validation Error

application/json

get

/v1/batch-inquiries/{batch_id}/inquiries

HTTPcURLJavaScriptPython

GET /v1/batch-inquiries/{batch_id}/inquiries HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "batchId": "123e4567-e89b-12d3-a456-426614174000",
  "inquiries": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "text",
      "status": "PLANNING",
      "businessName": "text",
      "businessCity": "text",
      "businessState": "text",
      "createdAt": "2026-03-25T13:20:55.314Z",
      "startedAt": "2026-03-25T13:20:55.314Z",
      "completedAt": "2026-03-25T13:20:55.314Z",
      "progress": {
        "stage": "queued",
        "currentStep": 1,
        "totalSteps": 4
      },
      "phaseProgress": {
        "currentPhase": "text",
        "processesTotal": 1,
        "processesCompleted": 1,
        "processesRunning": 1,
        "processesPending": 1,
        "phaseCounts": {
          "ANY_ADDITIONAL_PROPERTY": {
            "total": 1,
            "completed": 1,
            "succeeded": 1,
            "running": 1,
            "pending": 1
          }
        }
      },
      "businessSourceRecordsSummary": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "principalSourceRecordsSummary": {
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}