KYB Agent API - Reprompt

Overview

The /v1/us-kyb/reports endpoint lets you generate a KYB report for a US business from a business name and structured address. Reports are generated asynchronously. Create a report request, poll /v1/us-kyb/reports/{request_id} until it completes, then read the structured report payload and pdf_url. Completed reports can include:

IRS and tax-ID matching
Secretary of State records
address and physical-presence signals
officers and watchlist context
web and social presence
operating-status and business-consistency signals

Use the JSON response for application logic, and pdf_url when you need a rendered report for analyst review.

Full Example Report

{
  "request_id": "ecd7e4fc-54ee-40a9-819b-dac94a8d26ea",
  "status": "completed",
  "created_at": "2026-03-09T23:43:01.956609+00:00",
  "completed_at": "2026-03-09T23:44:07.955586+00:00",
  "report": {
    "report": {
      "business_status": "Not Verified",
      "last_updated": "03/09/2026 at 11:44PM UTC"
    },
    "scores": {
      "fraud_safety_score": 0,
      "loan_approval_score": 0,
      "reprompt_validation_score": 0
    },
    "submitted_information": {
      "business_name": {
        "value": "Connex Solutions LLC",
        "status": "Not Verified"
      },
      "tax_id": {
        "value": "Not Provided",
        "status": "Inconclusive"
      },
      "office_address": {
        "value": "4015 Travis Dr Ste 211, Nashville, TN 37211-3742, US",
        "status": "Inconclusive"
      }
    },
    "business_information": {
      "formation_state": "TN (UNVERIFIED)",
      "formation_date": "NOT_PROVIDED",
      "formation_date_relative": "NOT_PROVIDED",
      "entity_type": "NOT_PROVIDED",
      "tax_id": "Not Provided",
      "tax_id_status": "N/A",
      "tax_id_name_match": "Not Provided",
      "tax_id_name_match_status": "N/A"
    },
    "sos": {
      "status_counts": {
        "ACTIVE": 0,
        "INACTIVE": 1,
        "UNKNOWN": 0
      },
      "states": ["Inconclusive"],
      "secretary_of_state": [
        {
          "filing_id": "INCONCLUSIVE",
          "business_name": "Connex Solutions LLC",
          "jurisdiction": "Inconclusive",
          "status": "Inactive",
          "sub_status": "Foreign",
          "status_details": "Inconclusive",
          "address": "4015 Travis Dr Ste 211, Nashville, TN 37211-3742, US",
          "filed_date": "NOT_PROVIDED",
          "filed_relative": "NOT_PROVIDED",
          "entity_type": "NOT_PROVIDED",
          "source_url": "https://tnbear.tn.gov/Ecommerce/FilingSearch.aspx",
          "detailed_info": {
            "Formation Date": "NOT_PROVIDED",
            "Formation State": "TN (UNVERIFIED)",
            "Entity Type": "NOT_PROVIDED"
          },
          "registered_agent_name": "Not Provided",
          "registered_agent_lines": [
            "Not Provided"
          ],
          "principal_office_address": [
            "4015 Travis Dr Ste 211, Nashville, TN 37211-3742, US"
          ],
          "mailing_address": [
            "4015 Travis Dr Ste 211, Nashville, TN 37211-3742, US"
          ]
        }
      ]
    },
    "insights": {
      "office_address": { "status": "INCONCLUSIVE" },
      "watchlist": { "status": "INCONCLUSIVE" },
      "sos": { "status": "UNVERIFIED" },
      "tin_match": { "status": "INCONCLUSIVE" },
      "formation_state": { "status": "VERIFIED" }
    },
    "business_names": [
      { "name": "Connex Solutions LLC" }
    ],
    "online_presence": {
      "websites": [
        { "domain": "not_provided", "status": "Active" }
      ]
    },
    "office_addresses": [
      {
        "address": "4015 Travis Dr Ste 211, Nashville, TN 37211-3742, US"
      }
    ],
    "people": [
      { "name": "Unable to identify confirmed person", "roles": ["Unverified"] }
    ]
  },
  "pdf_url": "https://reprompt1.s3.amazonaws.com/kyb-agent-reports/connex-solutions-llc/20260309_234302/connex-solutions-llc_20260309_234302.pdf"
}

Start a Report

POST /v1/us-kyb/reports

Parameter	Type	Required	Description
`business_name`	string	Yes	Legal or trading name of the business
`address`	object	Yes	Structured US address
`submitted_by_name`	string	No	Name of the person requesting the report
`tin.number`	string	No	EIN or other tax ID
`stream`	boolean	No	Optional stream metadata flag

curl -X POST "https://api.reprompt.io/v1/us-kyb/reports" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "business_name": "Connex Solutions LLC",
    "submitted_by_name": "Alex Analyst",
    "address": {
      "address_line1": "4015 Travis Dr Ste 211",
      "city": "Nashville",
      "state": "TN",
      "postal_code": "37211-3742",
      "country_code": "US"
    },
    "tin": {
      "number": "33-3059213"
    }
  }'

{
  "request_id": "ecd7e4fc-54ee-40a9-819b-dac94a8d26ea",
  "status": "processing",
  "poll_url": "/v1/us-kyb/reports/ecd7e4fc-54ee-40a9-819b-dac94a8d26ea",
  "stream": null
}

Use request_id to poll for results.

Poll for Results

GET /v1/us-kyb/reports/

curl "https://api.reprompt.io/v1/us-kyb/reports/ecd7e4fc-54ee-40a9-819b-dac94a8d26ea" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response shape depends on the status field: processing, completed, or error. When status is completed, the response includes the full report object and a pdf_url pointing at the generated PDF in S3. Completed responses remain available for later polling. In production, I verified the same completed request still returned 200 more than 5 minutes after completion.

What the Report Covers

Each completed report returns a report object that may include sections like:

Section	What It Tells You
`report`	Business status and last-updated timestamp
`scores`	Reprompt-generated scoring outputs
`submitted_information`	Submitted business name, tax ID, and office address with verification status
`business_information`	Entity-level attributes like formation state, entity type, and tax-ID fields
`sos`	Secretary of State search results, status counts, and filing records when found
`insights`	Per-section rollups for SOS, address, watchlist, TIN, and formation-state checks
`business_names`	Known legal or alternate names
`online_presence`	Website and social signals when available
`office_addresses`	Address records returned by the report pipeline
`people`	Officer or principal names when identified

The exact fields present in report can vary by business, source coverage, and confidence level. Use defensive parsing rather than assuming every section or field will always be populated.

Report Sections in Detail

Report

Field	Type	Description
`business_status`	`string`	Top-level business verification outcome
`last_updated`	`string`	Timestamp string generated by the report pipeline

Scores

Live reports currently include score objects such as:

Field	Type	Description
`fraud_safety_score`	`integer`	Reprompt-generated fraud or safety score
`loan_approval_score`	`integer`	Reprompt-generated loan-approval-oriented score
`reprompt_validation_score`	`integer`	Reprompt validation/confidence score

Score keys may change over time as the report schema evolves. Prefer checking for keys before assuming a fixed score set.

Submitted Information

Field	Type	Description
`business_name`	`object`	`{ "value": string, "status": string }`
`tax_id`	`object`	`{ "value": string, "status": string }`
`office_address`	`object`	`{ "value": string, "status": string }`

Business Information

These fields are source-dependent and may contain verified values, placeholders, or inconclusive values:

Field	Type	Description
`formation_state`	`string`	State where the entity appears to have formed
`formation_date`	`string`	Formation date when available
`formation_date_relative`	`string`	Relative representation of formation date
`entity_type`	`string`	Entity type when available
`tax_id`	`string`	Tax identification number or placeholder
`tax_id_status`	`string`	Tax-ID verification status
`tax_id_name_match`	`string`	Business name associated with the TIN
`tax_id_name_match_status`	`string`	TIN/name match status

SOS (Secretary of State)

Field	Type	Description
`status_counts`	`object`	Counts across `ACTIVE`, `INACTIVE`, and `UNKNOWN` results
`states`	`string[]`	States or state-summary strings returned by the search
`secretary_of_state`	`array`	Filing or search records when available

Each filing record may include:

Field	Type	Description
`filing_id`	`string`	State filing ID or placeholder
`business_name`	`string`	Name as returned by the registry/source
`jurisdiction`	`string`	Domestic, foreign, or inconclusive
`status`	`string`	Active, inactive, or equivalent source status
`sub_status`	`string`	Additional status detail
`status_details`	`string`	More status context from the source
`address`	`string`	Address on file
`filed_date`	`string`	Filing date or placeholder
`filed_relative`	`string`	Relative representation of the filing date
`entity_type`	`string`	Entity type from the source
`source_url`	`string`	Link to the source registry or search page
`detailed_info`	`object`	Additional source-specific metadata
`registered_agent_name`	`string`	Registered agent name when available
`registered_agent_lines`	`string[]`	Registered agent address lines
`principal_office_address`	`string[]`	Principal office address lines
`mailing_address`	`string[]`	Mailing address lines

Insights

Per-section status rollups. Each key maps to { "status": string }. Common keys include:

Key	Example Status Values
`sos`	`UNVERIFIED`, `Submitted Active`
`tin_match`	`INCONCLUSIVE`, `Found`
`formation_state`	`VERIFIED`, `Found`
`office_address`	`INCONCLUSIVE`, `Verified`, `Failure`
`people`	`Verified`, `Unverified`
`watchlist`	`INCONCLUSIVE`, `Verified`
`business_name`	`Verified`, `Not Verified`

Business Names

Array of { "name": string } objects for legal names, alternate names, or DBAs when found.

Online Presence

Field	Type	Description
`websites`	`array`	`{ "domain": string, "status": string }`
`social_profiles`	`array`	`{ "platform": string, "name": string }` when available

Office Addresses

Array of address objects. Some reports include only address; others may also include boolean flags.

Field	Type	Description
`address`	`string`	Full address
`is_residential`	`boolean`	Present when residential classification is available
`is_deliverable`	`boolean`	Present when deliverability is available

People

Array of person objects:

Field	Type	Description
`name`	`string`	Full name or placeholder
`roles`	`string[]`	Roles such as officer, principal, or unverified

Error Response

{
  "request_id": "ecd7e4fc-54ee-40a9-819b-dac94a8d26ea",
  "status": "error",
  "created_at": "2026-03-09T23:43:01.956609+00:00",
  "error_at": "2026-03-09T23:44:07.955586+00:00",
  "error": {
    "code": "KYB_PROCESSING_FAILED",
    "message": "KYB generation failed."
  }
}

Office Addresses

Array of address objects:

Field	Type	Description
`address`	`string`	Full address
`is_residential`	`boolean`	`true` if residential, `false` if commercial (omitted if unknown)
`is_deliverable`	`boolean`	`true` if USPS deliverable (omitted if unknown)

People

Array of person objects:

Field	Type	Description
`name`	`string`	Full name
`roles`	`string[]`	Roles (e.g. `Primary Officer`, `Secondary Officer`)

Error Response

{
  "status": "error",
  "report_id": "rpt_9x8c7d6e5f4a",
  "created_at": "2026-02-23T10:30:00Z",
  "error_at": "2026-02-23T10:31:12Z",
  "business_name": "Nonexistent Corp",
  "business_address": "123 Fake St, Nowhere, XX 00000",
  "error": "Unable to verify business entity. No matching records found in any data source."
}

​Overview

​Full Example Report

​Start a Report

​POST /v1/us-kyb/reports

​Poll for Results

​GET /v1/us-kyb/reports/

​What the Report Covers

​Report Sections in Detail

​Report

​Scores

​Submitted Information

​Business Information

​SOS (Secretary of State)

​Insights

​Business Names

​Online Presence

​Office Addresses

​People

​Error Response

​Office Addresses

​People

​Error Response

Overview

Full Example Report

Start a Report

POST /v1/us-kyb/reports

Poll for Results

GET /v1/us-kyb/reports/

What the Report Covers

Report Sections in Detail

Report

Scores

Submitted Information

Business Information

SOS (Secretary of State)

Insights

Business Names

Online Presence

Office Addresses

People

Error Response

Office Addresses

People

Error Response