> ## Documentation Index > Fetch the complete documentation index at: https://docs.dataspike.io/llms.txt > Use this file to discover all available pages before exploring further. # Get the widget state > Returns the full widget state for a case: the server-authoritative section catalog merged with stored draft values, owners, documents and any open remediation notes. Authenticated solely by the public_id in the path. Documents render as slots (`documents[]` on a section): each slot lists its accepted types (`options`), required flag and uploaded files; person government IDs appear on the representative section slot and inside each owner entry. The parties section carries the per-owner form template in `fields` (values live in `owners`). Documents are uploaded via POST /api/v4/upload/kyb/{publicId}/documents (multipart, served by docver-upload). `kyc.persons[]` carries the representative's own KYC entry (`role: "representative"`), and, once the case has been submitted, each beneficial owner's personal KYC entry. The representative's entry carries `linked`: true whenever it currently shares identity with a beneficial owner selected via PUT .../representative/link, in which case its identity fields (name, dob, etc.) mirror that owner's and cannot be edited directly through PUT .../sections/representative/fields until unlinked. Find which owner by comparing this entry's `person_id` against each `owners[].applicant_id`. `sections` and `remediation` are TWO FORMS; branch on `status`. While an information request is open (the case is `in_remediation`) `remediation[]` carries the round in catalog order, every entry writable and holding the whole catalog definition of its target (`field` or `documents`, per `target_kind`) plus the officer's `message` and the target's `previous_value`; the whole of `sections` is `editable: false` for the duration. Outside a round `remediation` is absent and `sections` is the form as before. A field can be answerable without an entry of its own. An ask on a field with a `required_if` dependent reopens that dependent too, so picking "Other" in a reopened select (or ticking the operating address apart from the registered one) lets the specify-fields behind it be answered in the same body. They get no `remediation[]` entry, because the officer asked one question, and they read `editable: false` in `sections` like everything else there; render them under the target from that section's catalog definition. The widening is one hop off a real ask. A round may also carry asks the catalog does not define (`target_kind: custom`), listed after the catalog ones. Such an entry has no `section_key` / `field_key` and no `previous_value`; it carries a `custom` object with the officer's own `label`, `instruction` and `expectation`, the `resp_type` that says which controls to render (**text**, **file**, **text+file**), `required`, and the `answer_text` entered so far. Answer the text through POST /api/v4/kyb/widget/{publicId}/remediation under `custom`, addressing the ask by the entry's `item_id`; files are uploaded against that same identifier. `item_id` is present on every entry, custom or not. Every entry also carries `comment` / `comment_at`: the merchant's own note on that ask, absent until they leave one, written back through the same save under `comments` keyed by `item_id`. It rides beside the answer rather than being one, so an entry with a comment and no answer still counts in `items_open` and still stops the re-submit. The `custom` object carries two file lists, both by identity only (they are in no document slot): `documents` are the answers uploaded so far, each removable through the widget's document delete, and `reference_documents` are read-only examples the officer attached to the ask. Read an example through GET /api/v4/upload/kyb/{publicId}/remediation/reference/{documentId}; an example never counts as an answer. The form also carries what remediation did to it. A field a round has changed carries `original_value` (what was entered in the widget before any round touched it) and `remediation` (the round the current value came back from, plus `changes_count`); both are absent on a field no round reopened, where `value` IS the original. Asked about and reopened are not the same set: an ask on a field with a `required_if` dependent reopens that dependent too, so the specify-field behind an "Other" carries the pair of the ask that opened it without being a target of its own. A document replaced by a later upload keeps its slot with `superseded_at` set and `superseded_by_document_id` naming its replacement, listed after the live files and never `editable`. So `multiple` no longer bounds `documents[]`: it counts the LIVE files a slot takes, and a single-file slot (`multiple: false`) can list several documents. Read the live files by filtering `superseded_at == null` — one for a single-file slot, none once its last file was deleted — and treat the rest as the record of what came before. Do not read `documents[0]`: live-before-superseded is the order the response happens to be built in, not part of this contract. ## OpenAPI ````yaml https://api.dataspike.io/openapi/kyb/public.json get /api/v4/kyb/widget/{publicId} openapi: 3.1.0 info: description: Know Your Business (KYB) — case creation and the embedded onboarding widget. title: Dataspike KYB API version: '1.0' servers: [] security: [] paths: /api/v4/kyb/widget/{publicId}: get: tags: - KYB Widget summary: Get the widget state description: >- Returns the full widget state for a case: the server-authoritative section catalog merged with stored draft values, owners, documents and any open remediation notes. Authenticated solely by the public_id in the path. Documents render as slots (`documents[]` on a section): each slot lists its accepted types (`options`), required flag and uploaded files; person government IDs appear on the representative section slot and inside each owner entry. The parties section carries the per-owner form template in `fields` (values live in `owners`). Documents are uploaded via POST /api/v4/upload/kyb/{publicId}/documents (multipart, served by docver-upload). `kyc.persons[]` carries the representative's own KYC entry (`role: "representative"`), and, once the case has been submitted, each beneficial owner's personal KYC entry. The representative's entry carries `linked`: true whenever it currently shares identity with a beneficial owner selected via PUT .../representative/link, in which case its identity fields (name, dob, etc.) mirror that owner's and cannot be edited directly through PUT .../sections/representative/fields until unlinked. Find which owner by comparing this entry's `person_id` against each `owners[].applicant_id`. `sections` and `remediation` are TWO FORMS; branch on `status`. While an information request is open (the case is `in_remediation`) `remediation[]` carries the round in catalog order, every entry writable and holding the whole catalog definition of its target (`field` or `documents`, per `target_kind`) plus the officer's `message` and the target's `previous_value`; the whole of `sections` is `editable: false` for the duration. Outside a round `remediation` is absent and `sections` is the form as before. A field can be answerable without an entry of its own. An ask on a field with a `required_if` dependent reopens that dependent too, so picking "Other" in a reopened select (or ticking the operating address apart from the registered one) lets the specify-fields behind it be answered in the same body. They get no `remediation[]` entry, because the officer asked one question, and they read `editable: false` in `sections` like everything else there; render them under the target from that section's catalog definition. The widening is one hop off a real ask. A round may also carry asks the catalog does not define (`target_kind: custom`), listed after the catalog ones. Such an entry has no `section_key` / `field_key` and no `previous_value`; it carries a `custom` object with the officer's own `label`, `instruction` and `expectation`, the `resp_type` that says which controls to render (**text**, **file**, **text+file**), `required`, and the `answer_text` entered so far. Answer the text through POST /api/v4/kyb/widget/{publicId}/remediation under `custom`, addressing the ask by the entry's `item_id`; files are uploaded against that same identifier. `item_id` is present on every entry, custom or not. Every entry also carries `comment` / `comment_at`: the merchant's own note on that ask, absent until they leave one, written back through the same save under `comments` keyed by `item_id`. It rides beside the answer rather than being one, so an entry with a comment and no answer still counts in `items_open` and still stops the re-submit. The `custom` object carries two file lists, both by identity only (they are in no document slot): `documents` are the answers uploaded so far, each removable through the widget's document delete, and `reference_documents` are read-only examples the officer attached to the ask. Read an example through GET /api/v4/upload/kyb/{publicId}/remediation/reference/{documentId}; an example never counts as an answer. The form also carries what remediation did to it. A field a round has changed carries `original_value` (what was entered in the widget before any round touched it) and `remediation` (the round the current value came back from, plus `changes_count`); both are absent on a field no round reopened, where `value` IS the original. Asked about and reopened are not the same set: an ask on a field with a `required_if` dependent reopens that dependent too, so the specify-field behind an "Other" carries the pair of the ask that opened it without being a target of its own. A document replaced by a later upload keeps its slot with `superseded_at` set and `superseded_by_document_id` naming its replacement, listed after the live files and never `editable`. So `multiple` no longer bounds `documents[]`: it counts the LIVE files a slot takes, and a single-file slot (`multiple: false`) can list several documents. Read the live files by filtering `superseded_at == null` — one for a single-file slot, none once its last file was deleted — and treat the rest as the record of what came before. Do not read `documents[0]`: live-before-superseded is the order the response happens to be built in, not part of this contract. operationId: GET_/api/v4/kyb/widget/:publicId parameters: - description: KYB case public id. in: path name: publicId required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/StateResponse' application/xml: schema: $ref: '#/components/schemas/StateResponse' description: Widget state. '404': content: application/json: schema: $ref: '#/components/schemas/ErrCaseNotFound' application/xml: schema: $ref: '#/components/schemas/ErrCaseNotFound' description: Case not found. components: schemas: StateResponse: description: StateResponse schema example: id: 019f179b-0fa7-72c8-818e-819652540477 sections: - fields: - editable: true key: legal_name label: Legal Business Name required: true type: text validation: min_len: 1 max_len: 200 value: null - editable: true key: dba label: DBA (Doing Business As) required: false type: text value: null - editable: true key: entity_type label: Entity Type options: - Sole Proprietorship - Limited Liability Company (LLC) - Corporation - Limited Partnership (LP) - Limited Liability Partnership (LLP) - S - Corp - C - Corp required: true type: select value: null key: business kind: fields title: Business details - fields: - editable: true key: registration_type label: Business Registration Type options: - EIN - CRN - SSN - ITIN - NPWP - LEI - Other required: true type: select value: null - editable: true key: registration_type_other label: Specify registration type required: false required_if: field: registration_type value: Other type: text value: null - editable: true key: industry_type label: Industry Type options: - Electronics - General Retail - Other required: true type: select value: null - editable: true key: industry_type_other label: Specify industry required: false required_if: field: industry_type value: Other type: text value: null - editable: true key: mcc label: Merchant Category Code (MCC) options: - 5732 - ELECTRONIC SALES - 5999 - MISCELLANEOUS AND SPECIALTY RETAIL STORES required: true type: select value: null key: registration kind: fields title: Business registration - fields: - editable: true key: rep_full_name label: Full Name required: true type: text validation: min_len: 1 max_len: 200 value: null - editable: true key: rep_dob label: Date of Birth required: true type: date value: null - editable: true key: rep_mobile label: Mobile Number required: true type: phone value: null - editable: true key: rep_citizenship label: Citizenship / Residency options: - U.S. citizen - U.S. permanent resident - Non-U.S. citizen / resident required: true type: select value: null - editable: true key: rep_ssn label: SSN / Tax ID required: true type: text value: null key: representative kind: fields title: Authorized representative - documents: - documents: [] editable: true key: owner_id_doc label: Government ID multiple: true options: - Passport - Drivers License - State ID - Permanent Resident Card (Green Card) required: true fields: - editable: true key: full_name label: Full Name required: true type: text validation: min_len: 1 max_len: 200 value: null - editable: true key: dob label: Date of Birth required: true type: date value: null - editable: true key: ssn label: SSN / Tax ID required: true type: text value: null - editable: true key: ownership_pct label: '% Ownership' required: true type: number value: null key: people kind: parties owners: - applicant_id: 019f1383-8f38-7d31-b921-39310a19b444 citizenship: U.S. citizen dob: '1990-01-01' documents: - created_at: '2026-06-30T08:15:00Z' editable: true filename: john_passport.pdf id: 019f18a1-0000-7000-8000-0123456789ab type: Passport editable: true email: john@acme.com full_name: John Doe id: 019f18a0-0000-7000-8000-0123456789ab ownership_pct: 40 role: Beneficial Owner (≥25%) ssn: 123-45-6789 title: Beneficial owners - documents: - documents: [] editable: true key: tax label: Tax identification multiple: false note: Upload one of the following documents options: - IRS EIN Confirmation Letter - W-9 Form - ITIN Assignment Letter - Federal Tax Return required: true - documents: [] editable: true key: bank label: Bank account / payout multiple: false options: - Bank Statement - ACH / Direct Deposit Authorization required: true - documents: [] editable: true key: registration label: Certificate of Registration / Incorporation multiple: false options: - Certificate of Registration / Incorporation required: true - documents: [] editable: true key: operating_agreement label: Operating Agreement multiple: false note: Required for LLCs and partnerships options: - Operating Agreement required: false - documents: [] editable: true key: pci label: PCI SAQ multiple: false options: - SAQ A - SAQ A-EP - SAQ D required: true - documents: [] editable: true key: additional label: Additional documents multiple: true options: - Other required: false key: documents kind: documents title: Documents status: draft properties: checks_summary: nullable: true properties: checks: items: properties: completed_at: format: date-time nullable: true type: string instances: nullable: true properties: completed: example: 3 type: integer expected: example: 8 type: integer type: object severity: enum: - low - medium - high example: low nullable: true type: string status: enum: - pending - in_progress - completed - error example: completed type: string type: enum: - registry - tin - document_verification - doc_manipulation - aml_company - aml_person - cross_check - business_risk_score - agentic_verification - website_triage - web_adverse_media - kyc - kyc_ubo example: registry type: string verdict: example: active nullable: true type: string type: object type: array completed: example: 6 type: integer errored: example: 0 type: integer expected: example: 7 type: integer failed: example: 0 type: integer passed: example: 4 type: integer review: example: 2 type: integer type: object id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string info_request: nullable: true properties: items_open: example: 1 type: integer items_total: example: 2 type: integer status: enum: - draft - sent - received - canceled example: sent type: string type: object kyc: nullable: true properties: persons: items: properties: completed_at: format: date-time nullable: true type: string email: example: owner@example.com nullable: true type: string linked: nullable: true type: boolean name: example: John Smith nullable: true type: string ownership_pct: example: 25 format: double nullable: true type: number person_id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string role: example: representative type: string status: example: not_started type: string verification_id: example: 0195c1f0-1234-7000-8000-0123456789ab nullable: true type: string verification_status: example: verified nullable: true type: string verification_url: example: https://verify.dataspike.io/vAbC0123456789 nullable: true type: string verification_url_id: example: vAbC0123456789 nullable: true type: string type: object type: array type: object remediation: items: example: item_id: 019f17aa-1b2c-73d4-95e6-0123456789ab section_key: registration field_key: registration_number target_kind: field message: The number does not match the registry, please re-enter it. comment: >- The registry still lists our old name; the rename filing is with them since May. comment_at: '2026-07-02T10:20:00Z' previous_value: 36-2382XXX field: key: registration_number label: Registration number type: text required: true value: 36-2382580 editable: true nullable: true properties: comment: example: >- The registry still lists our old name; the rename filing is attached. nullable: true type: string comment_at: format: date-time nullable: true type: string custom: example: label: Proof of address instruction: >- A utility bill showing the company name and the registered address. expectation: Issued within the last 3 months. resp_type: text+file required: true answer_text: Suite 400, 1 Market Street, San Francisco, CA 94105. documents: - id: 019c9c44-6b7c-7aa4-a5c0-abc123def333 name: utility_bill_2026_06.pdf reference_documents: - id: 019c9c45-7c8d-7aa4-a5c0-abc123def444 name: utility_bill_example.pdf nullable: true properties: answer_text: example: Suite 400, 1 Market Street. nullable: true type: string documents: items: properties: id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string name: example: bank-statement-2026-07.pdf type: string type: object type: array expectation: example: Issued within the last 3 months. type: string instruction: example: A utility bill or a bank statement. type: string label: example: Proof of address type: string reference_documents: items: properties: id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string name: example: bank-statement-2026-07.pdf type: string type: object type: array required: example: true type: boolean resp_type: enum: - text - file - text+file example: text+file type: string type: object documents: nullable: true properties: documents: items: properties: created_at: format: date-time type: string editable: example: true type: boolean filename: example: w9.pdf nullable: true type: string id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string superseded_at: format: date-time nullable: true type: string superseded_by_document_id: example: 0195c1f0-1234-7000-8000-0123456789ab nullable: true type: string type: example: Bank Statement type: string type: object type: array editable: example: true type: boolean key: example: tax type: string label: example: Tax identification type: string multiple: example: false type: boolean note: nullable: true type: string options: items: type: string type: array required: example: true type: boolean type: object field: nullable: true properties: default: example: US nullable: true type: string editable: example: true type: boolean key: example: legal_name type: string label: example: Legal Business Name type: string options: items: nullable: true type: string nullable: true type: array original_value: nullable: true remediation: nullable: true properties: changes_count: example: 2 type: integer remediation_item_id: example: 019f179b-0fa7-72c8-818e-819652540477 type: string request_id: example: 019f179b-0fa7-72c8-818e-819652540477 type: string updated_at: format: date-time type: string type: object required: example: true type: boolean required_if: nullable: true properties: field: type: string value: type: string type: object type: enum: - text - number - email - phone - date - select - bool - country - mcc - address example: text type: string validation: nullable: true properties: max_len: nullable: true type: integer min_len: nullable: true type: integer pattern: nullable: true type: string type: object value: nullable: true type: object field_key: example: registration_number nullable: true type: string item_id: example: 019f179b-0fa7-72c8-818e-819652540477 type: string message: example: The number does not match the registry, please re-enter it. type: string previous_value: nullable: true section_key: example: registration nullable: true type: string target_kind: enum: - field - document - custom example: field type: string type: object nullable: true type: array sections: items: properties: documents: items: nullable: true properties: documents: items: properties: created_at: format: date-time type: string editable: example: true type: boolean filename: example: w9.pdf nullable: true type: string id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string superseded_at: format: date-time nullable: true type: string superseded_by_document_id: example: 0195c1f0-1234-7000-8000-0123456789ab nullable: true type: string type: example: Bank Statement type: string type: object type: array editable: example: true type: boolean key: example: tax type: string label: example: Tax identification type: string multiple: example: false type: boolean note: nullable: true type: string options: items: type: string type: array required: example: true type: boolean type: object nullable: true type: array fields: items: nullable: true properties: default: example: US nullable: true type: string editable: example: true type: boolean key: example: legal_name type: string label: example: Legal Business Name type: string options: items: nullable: true type: string nullable: true type: array original_value: nullable: true remediation: nullable: true properties: changes_count: example: 2 type: integer remediation_item_id: example: 019f179b-0fa7-72c8-818e-819652540477 type: string request_id: example: 019f179b-0fa7-72c8-818e-819652540477 type: string updated_at: format: date-time type: string type: object required: example: true type: boolean required_if: nullable: true properties: field: type: string value: type: string type: object type: enum: - text - number - email - phone - date - select - bool - country - mcc - address example: text type: string validation: nullable: true properties: max_len: nullable: true type: integer min_len: nullable: true type: integer pattern: nullable: true type: string type: object value: nullable: true type: object nullable: true type: array key: example: business type: string kind: enum: - fields - parties - documents example: fields type: string owners: items: nullable: true properties: address_city: nullable: true type: string address_country: nullable: true type: string address_postal: nullable: true type: string address_state: nullable: true type: string address_street: nullable: true type: string applicant_id: nullable: true type: string citizenship: nullable: true type: string dob: nullable: true type: string documents: items: properties: created_at: format: date-time type: string editable: example: true type: boolean filename: example: w9.pdf nullable: true type: string id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string superseded_at: format: date-time nullable: true type: string superseded_by_document_id: example: 0195c1f0-1234-7000-8000-0123456789ab nullable: true type: string type: example: Bank Statement type: string type: object type: array editable: example: true type: boolean email: nullable: true type: string full_name: nullable: true type: string id: example: 0195c1f0-1234-7000-8000-0123456789ab type: string mobile: nullable: true type: string ownership_pct: format: double nullable: true type: number role: nullable: true type: string source: enum: - widget - dashboard example: widget type: string ssn: nullable: true type: string type: object nullable: true type: array status: nullable: true type: string title: example: Business type: string type: object type: array status: example: draft type: string type: object ErrCaseNotFound: description: ErrCaseNotFound schema example: code: case_not_found message: Case not found properties: code: example: email_otp_expired type: string message: example: OTP has expired type: string param: nullable: true type: string type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.