> ## Documentation Index
> Fetch the complete documentation index at: https://developer.finogates.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create User KYB Record

> Submit business verification (KYB) details for one user. You can also attach supporting documents as files along with the details.

The **`payload`** field is a JSON object with this shape:

- `business_legal_name` (string, **required**) — the official registered name of the business.
- `business_ein` (string, optional) — the business's US federal tax ID (EIN).
- `business_data` (object, optional) — structured business details:
    - `business_type`, `dba`, `website`, `registration_number`, `formation_date`, `mcc`, `business_description`
    - `business_email`, `business_phone`, `phone_country_code` — business contact details
    - `contact_first_name`, `contact_last_name`, `contact_email` — the contact person
    - `business_address` (object) — `line1`, `city`, `state`, `postal_code`, `country`
    - `ownership` (array) — the beneficial owners, each `{ name, role, ownership_pct }`

Any field not listed above is still accepted and stored.

Example `payload`:

```json
{
  "business_legal_name": "Lovelace Analytics LLC",
  "business_ein": "12-3456789",
  "business_data": {
    "business_type": "llc",
    "dba": "Lovelace Analytics",
    "website": "https://lovelace.example.com",
    "business_address": {
      "line1": "500 Terry Francois Blvd",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94158",
      "country": "US"
    },
    "ownership": [
      { "name": "Ada Lovelace", "role": "founder", "ownership_pct": 100 }
    ]
  }
}
```



## OpenAPI

````yaml POST /v1/platform/users/kyb/start/{user_id}
openapi: 3.1.0
info:
  title: Finogate Platform API v1
  version: 0.1.0
servers:
  - url: https://api-sandbox.finogates.com
    description: Sandbox
  - url: https://api.finogates.com
    description: Production
security: []
tags:
  - name: auth
  - name: users
  - name: payees
  - name: verification
  - name: bank accounts
  - name: card processing
  - name: digital-assets
  - name: international
  - name: onboarding
  - name: pending-applications
  - name: wallets
  - name: payments
  - name: catalog
  - name: webhooks
  - name: phone-numbers
  - name: sms
  - name: calls
  - name: listings
  - name: embed-tokens
paths:
  /v1/platform/users/kyb/start/{user_id}:
    post:
      tags:
        - verification
      summary: Submit a User's Business Check
      description: >-
        Submit business verification (KYB) details for one user. You can also
        attach supporting documents as files along with the details.


        The **`payload`** field is a JSON object with this shape:


        - `business_legal_name` (string, **required**) — the official registered
        name of the business.

        - `business_ein` (string, optional) — the business's US federal tax ID
        (EIN).

        - `business_data` (object, optional) — structured business details:
            - `business_type`, `dba`, `website`, `registration_number`, `formation_date`, `mcc`, `business_description`
            - `business_email`, `business_phone`, `phone_country_code` — business contact details
            - `contact_first_name`, `contact_last_name`, `contact_email` — the contact person
            - `business_address` (object) — `line1`, `city`, `state`, `postal_code`, `country`
            - `ownership` (array) — the beneficial owners, each `{ name, role, ownership_pct }`

        Any field not listed above is still accepted and stored.


        Example `payload`:


        ```json

        {
          "business_legal_name": "Lovelace Analytics LLC",
          "business_ein": "12-3456789",
          "business_data": {
            "business_type": "llc",
            "dba": "Lovelace Analytics",
            "website": "https://lovelace.example.com",
            "business_address": {
              "line1": "500 Terry Francois Blvd",
              "city": "San Francisco",
              "state": "CA",
              "postal_code": "94158",
              "country": "US"
            },
            "ownership": [
              { "name": "Ada Lovelace", "role": "founder", "ownership_pct": 100 }
            ]
          }
        }

        ```
      operationId: create_user_kyb_v1_platform_users_kyb_start__user_id__post
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_create_user_kyb_v1_platform_users_kyb_start__user_id__post
            encoding:
              payload:
                contentType: application/json
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse_KybRecordRead_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - _AuthenticatedBearer: []
components:
  schemas:
    Body_create_user_kyb_v1_platform_users_kyb_start__user_id__post:
      properties:
        payload:
          additionalProperties: false
          example:
            business_data:
              business_address:
                city: San Francisco
                country: US
                line1: 500 Terry Francois Blvd
                postal_code: '94158'
                state: CA
              business_email: ops@lovelace.example.com
              business_phone: '+14155550199'
              business_type: llc
              dba: Lovelace Analytics
              formation_date: '2021-04-12'
              ownership:
                - name: Ada Lovelace
                  ownership_pct: 100
                  role: founder
              website: https://lovelace.example.com
            business_ein: 12-3456789
            business_legal_name: Lovelace Analytics LLC
          properties:
            business_legal_name:
              description: The official registered name of the business.
              maxLength: 255
              minLength: 1
              title: Business Legal Name
              type: string
            business_ein:
              anyOf:
                - type: string
                  maxLength: 40
                - type: 'null'
              default: null
              description: >-
                The business's US federal tax ID, also called an Employer
                Identification Number (EIN). Optional.
              title: Business Ein
            business_data:
              $ref: '#/components/schemas/KybBusinessData'
              description: Structured business details to verify.
          required:
            - business_legal_name
          title: KybRecordCreate
          type: object
          description: The business verification details, sent as JSON text.
        files:
          items:
            type: string
            format: binary
          type: array
          title: Files
      type: object
      required:
        - payload
      title: Body_create_user_kyb_v1_platform_users_kyb_start__user_id__post
    CommonResponse_KybRecordRead_:
      properties:
        status_code:
          type: integer
          title: Status Code
          description: HTTP status code for the response.
        data:
          $ref: '#/components/schemas/KybRecordRead'
          description: Payload or error details.
        query_generated_time:
          type: integer
          title: Query Generated Time
          description: >-
            UTC timestamp (milliseconds since epoch) when response was
            generated.
      type: object
      required:
        - status_code
        - data
        - query_generated_time
      title: CommonResponse[KybRecordRead]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    KybBusinessData:
      additionalProperties: true
      description: |-
        Structured business details submitted for verification.

        Every field is optional. Fields not listed here are still accepted and
        stored, but only the documented fields are guaranteed to be understood.
      properties:
        business_type:
          anyOf:
            - type: string
              maxLength: 80
            - type: 'null'
          default: null
          description: Legal structure of the business, for example "llc" or "corporation".
          title: Business Type
        dba:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          default: null
          description: >-
            Trading name ("doing business as"), if different from the legal
            name.
          title: Dba
        website:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          default: null
          description: Public website address of the business.
          title: Website
        registration_number:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          default: null
          description: Government business registration or incorporation number.
          title: Registration Number
        formation_date:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          default: null
          description: Date the business was formed, written as YYYY-MM-DD.
          title: Formation Date
        mcc:
          anyOf:
            - type: string
              maxLength: 8
            - type: 'null'
          default: null
          description: >-
            Merchant Category Code — the four-digit number that classifies the
            business's industry.
          title: Mcc
        business_description:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: A short description of what the business does.
          title: Business Description
        business_email:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          default: null
          description: Main contact email address for the business.
          title: Business Email
        business_phone:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          default: null
          description: Main contact phone number for the business.
          title: Business Phone
        phone_country_code:
          anyOf:
            - maxLength: 12
              type: string
            - type: 'null'
          default: null
          description: Dialing code for the phone number, for example "+1".
          title: Phone Country Code
        contact_first_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          default: null
          description: First name of the main contact person.
          title: Contact First Name
        contact_last_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          default: null
          description: Last name of the main contact person.
          title: Contact Last Name
        contact_email:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          default: null
          description: Email address of the main contact person.
          title: Contact Email
        business_address:
          anyOf:
            - $ref: '#/components/schemas/KybBusinessAddress'
            - type: 'null'
          default: null
          description: Registered address of the business.
        ownership:
          anyOf:
            - items:
                $ref: '#/components/schemas/KybBeneficialOwner'
              type: array
            - type: 'null'
          default: null
          description: The people who own the business (its beneficial owners).
          title: Ownership
        business_documents:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: >-
            References to supporting documents. Normally filled in automatically
            from the files you upload — you do not need to set this yourself.
          title: Business Documents
      title: KybBusinessData
      type: object
    KybRecordRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        status:
          type: string
          title: Status
        approved_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Approved At
        rejected_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Rejected At
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        decline_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Decline Reason
        user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: User Id
        subject_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Subject Email
        subject_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Subject Name
        business_legal_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Legal Name
        business_ein:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Ein
        business_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Type
        dba:
          anyOf:
            - type: string
            - type: 'null'
          title: Dba
        website:
          anyOf:
            - type: string
            - type: 'null'
          title: Website
        registration_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Registration Number
        formation_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Formation Date
        mcc:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcc
        business_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Description
        business_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Email
        business_phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Business Phone
        phone_country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Country Code
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        zip:
          anyOf:
            - type: string
            - type: 'null'
          title: Zip
        contact_first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact First Name
        contact_last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact Last Name
        contact_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact Email
        business_documents:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Business Documents
        ownership:
          anyOf:
            - items:
                $ref: '#/components/schemas/KybBeneficialOwner'
              type: array
            - type: 'null'
          title: Ownership
      type: object
      required:
        - id
        - status
        - created_at
        - updated_at
      title: KybRecordRead
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    KybBusinessAddress:
      additionalProperties: true
      description: Registered address of a business, used inside :class:`KybBusinessData`.
      properties:
        line1:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          default: null
          description: Street address.
          title: Line1
        city:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          default: null
          description: City.
          title: City
        state:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          default: null
          description: State, province, or region.
          title: State
        postal_code:
          anyOf:
            - type: string
              maxLength: 40
            - type: 'null'
          default: null
          description: ZIP or postal code.
          title: Postal Code
        country:
          anyOf:
            - type: string
              maxLength: 80
            - type: 'null'
          default: null
          description: Two-letter country code, for example "US".
          title: Country
      title: KybBusinessAddress
      type: object
    KybBeneficialOwner:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: Full legal name of the owner.
        role:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Role
          description: >-
            The owner's role in the business, for example "founder" or
            "director".
        ownership_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Ownership Pct
          description: >-
            Share of the business this person owns, as a percentage from 0 to
            100.
      additionalProperties: true
      type: object
      required:
        - name
      title: KybBeneficialOwner
      description: A person who owns part of the business.
  securitySchemes:
    _AuthenticatedBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /v1/platform/auth/token

````