> ## Documentation Index
> Fetch the complete documentation index at: https://syncupai-claude-update-docs-terminology-g7r40.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# KYB Agent API

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

## Overview

The [`/v1/us-kyb/reports`](/api-reference/create-a-us-kyb-report-request) 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}`](/api-reference/poll-a-us-kyb-report-request) 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

```json theme={null}
{
  "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            |

```bash theme={null}
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"
    }
  }'
```

```json theme={null}
{
  "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/{request_id}

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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."
}
```