Submit a User's Business Check

curl --request POST \
  --url https://api-sandbox.finogates.com/v1/platform/users/kyb/start/{user_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'payload={
  "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"
}' \
  --form 'files=<string>' \
  --form files.items='@example-file'

{
  "status_code": 123,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "approved_at": "2023-11-07T05:31:56Z",
    "rejected_at": "2023-11-07T05:31:56Z",
    "decline_reason": "<string>",
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "subject_email": "<string>",
    "subject_name": "<string>",
    "business_legal_name": "<string>",
    "business_ein": "<string>",
    "business_type": "<string>",
    "dba": "<string>",
    "website": "<string>",
    "registration_number": "<string>",
    "formation_date": "<string>",
    "mcc": "<string>",
    "business_description": "<string>",
    "business_email": "<string>",
    "business_phone": "<string>",
    "phone_country_code": "<string>",
    "address": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zip": "<string>",
    "contact_first_name": "<string>",
    "contact_last_name": "<string>",
    "contact_email": "<string>",
    "business_documents": [
      "<string>"
    ],
    "ownership": [
      {
        "name": "<string>",
        "role": "<string>",
        "ownership_pct": 50
      }
    ]
  },
  "query_generated_time": 123
}

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:

{
  "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 }
    ]
  }
}

POST

platform

users

kyb

start

{user_id}

Submit a User's Business Check

curl --request POST \
  --url https://api-sandbox.finogates.com/v1/platform/users/kyb/start/{user_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'payload={
  "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"
}' \
  --form 'files=<string>' \
  --form files.items='@example-file'

{
  "status_code": 123,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "approved_at": "2023-11-07T05:31:56Z",
    "rejected_at": "2023-11-07T05:31:56Z",
    "decline_reason": "<string>",
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "subject_email": "<string>",
    "subject_name": "<string>",
    "business_legal_name": "<string>",
    "business_ein": "<string>",
    "business_type": "<string>",
    "dba": "<string>",
    "website": "<string>",
    "registration_number": "<string>",
    "formation_date": "<string>",
    "mcc": "<string>",
    "business_description": "<string>",
    "business_email": "<string>",
    "business_phone": "<string>",
    "phone_country_code": "<string>",
    "address": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zip": "<string>",
    "contact_first_name": "<string>",
    "contact_last_name": "<string>",
    "contact_email": "<string>",
    "business_documents": [
      "<string>"
    ],
    "ownership": [
      {
        "name": "<string>",
        "role": "<string>",
        "ownership_pct": 50
      }
    ]
  },
  "query_generated_time": 123
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

user_id

string<uuid>

required

Body

multipart/form-data

payload

KybRecordCreate · object

required

The business verification details, sent as JSON text.

Show child attributes

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

files

file[]

Response

Successful Response

status_code

integer

required

HTTP status code for the response.

data

KybRecordRead · object

required

Payload or error details.

Show child attributes

query_generated_time

integer

required

UTC timestamp (milliseconds since epoch) when response was generated.

Sync User KYC Add Bank Account