KYB Agent API

Automated Know Your Business (KYB) verification reports via API.

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."
}