Submit Business Details

Writes the business's own details: who it is, its tax id, its formation, and its registered and operating addresses. The body replaces the whole set: a field you leave out is cleared, which is how a wrong value is removed, so send every field you have each time. Owners and documents have their own endpoints and are not touched.

Every field is optional here, so a form can be saved half filled. Completeness is required only when you request verification; ready in the response says whether the business's part is done.

The details can be written while the record is pending, ready_for_review or needs_update. Once it is in_review, approved or rejected they are locked (409).

Takes a workspace-scoped API key or a dashboard session. An account-scoped key is refused with 401.

Replaces the details half of POST /api/v2/kyb/banking-verification/business.

Authorization:

Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.

Headers:
  Authorization: APIKey {SIGNED_JWT}

How to build and sign the JWT: Authentication.

Endpoint

PATCH

/v3/customers/{customer_id}/kyb

Path parameters

Parameter	Type	Description
`customer_id`	string (`cst_…`)	Required. The business customer. Its record must be open.

Request Body Sample

{
  "name": "Acme Robotics Inc",
  "dba_name": "Acme Robotics",
  "entity_type": "corporation",
  "phone": "+14155550123",
  "email": "ops@acmerobotics.example.com",
  "website": "https://acmerobotics.example.com",
  "id_number": "12-3456789",
  "id_document_type": "ein",
  "tax_number": "12-3456789",
  "formation_date": "2019-06-01",
  "incorporation_state": "DE",
  "address": {
    "line1": "500 Terry A Francois Blvd",
    "line2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94158",
    "country": "US"
  },
  "operation_address": {
    "line1": "1 Market St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  }
}

Request Body Schema

"Needed to request verification" marks the fields Request Verification requires.

Field	Type	Description
`name`	string	Legal name. Up to 255 characters. Needed to request verification.
`dba_name`	string	Doing-business-as name. Up to 255 characters.
`entity_type`	string	Legal structure: `sole_proprietor`, `limited_liability_company`, `general_partnership`, `limited_liability_partnership`, `corporation`, `publicly_traded_company`, `non_profit` or `government_organization`. Needed to request verification.
`phone`	string	E.164 format, e.g. `+14155550123`.
`email`	string	Contact email.
`website`	string	A URL, e.g. `https://acmerobotics.example.com`.
`id_number`	string	The business's tax id (EIN). 2 to 20 characters. Needed to request verification.
`id_document_type`	string	What backs `id_number`. The only value is `ein`. Needed to request verification.
`tax_number`	string	Tax number, where it differs from the EIN. Up to 255 characters.
`formation_date`	string	`YYYY-MM-DD`. Needed to request verification.
`incorporation_state`	string	State of incorporation, e.g. `DE`. Up to 100 characters. Needed to request verification.
`address`	address	Registered address.
`operation_address`	address	Where the business operates, when that differs from `address`.

An address has these fields:

Field	Type	Description
`line1`	string	Up to 255 characters.
`line2`	string	Optional. Up to 255 characters.
`city`	string	Up to 100 characters.
`state`	string	Up to 100 characters.
`postal_code`	string	Must fit the country's postal code format.
`country`	string	ISO 3166-1 alpha-2, e.g. `US`.

An address is either left out or complete: once any of its fields is set, line1, city, state, postal_code and country are all required.

Response Sample

{
  "id": "kyb_01m24es440fqxr7z5xsphsmvqm",
  "customer_id": "cst_01m24bb8g0f28rhegcwp8rfbqd",
  "status": "pending",
  "status_reason": "verification record created",
  "name": "Acme Robotics Inc",
  "dba_name": "Acme Robotics",
  "entity_type": "corporation",
  "phone": "+14155550123",
  "email": "ops@acmerobotics.example.com",
  "website": "https://acmerobotics.example.com",
  "id_number": "12-3456789",
  "id_document_type": "ein",
  "tax_number": "12-3456789",
  "formation_date": "2019-06-01",
  "incorporation_state": "DE",
  "address": {
    "line1": "500 Terry A Francois Blvd",
    "line2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94158",
    "country": "US"
  },
  "operation_address": {
    "line1": "1 Market St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "ready": true,
  "event_history": [
    {
      "status": "pending",
      "status_reason": "verification record created",
      "date": "2026-09-09T14:20:00Z"
    }
  ],
  "created_at": "2026-09-09T14:20:00Z",
  "updated_at": "2026-09-09T14:32:10Z"
}

Response Schema

The record after the write, as in Get Business Verification. When a document is completed too and every owner is ready_for_review (a status only External Owner Verification sets), status may come back as ready_for_review.

Errors

Status	`message`	When
`400`	`failed to parse request`	The body is not valid JSON, `entity_type` or `id_document_type` is not one of its values, or `customer_id` is not a `cst_…` TypeID.
`400`	`invalid_address`	An address is only partly filled in.
`400`	`invalid_country`	An address has other fields but no `country`.
`401`	`unauthorized`	Missing or invalid signature, or an account-scoped key or customer session.
`403`	`forbidden`	A dashboard member whose role does not allow this. A workspace-scoped key always may.
`404`	`kyb_not_found`	This customer has no record. Open it first.
`409`	`kyb_verification_in_flight`	The record is `in_review`.
`409`	`kyb_already_approved`	The record is `approved`.
`409`	`kyb_rejected`	The record is `rejected`.
`422`	`Validation failed`	A value has the wrong format or length (`phone`, `email`, `website`, `formation_date`, a `country`, a `postal_code`, a length limit); `details` names the field.

Coming from v2

v2 (`POST /api/v2/kyb/banking-verification/business`)	v3
every field required	every field optional; completeness is checked at request verification
`accountId` (body, uuid)	`customer_id` (path, `cst_…`)
camelCase: `dbaName`, `idNumber`, `idDocumentType`, `taxNumber`, `entityType`, `formationDate`, `incorporationState`, `operationAddress`	snake_case: `dba_name`, `id_number`, `id_document_type`, `tax_number`, `entity_type`, `formation_date`, `incorporation_state`, `operation_address`
`address1`, `address2`, `postalCode`	`line1`, `line2`, `postal_code`
no email	`email`
editable in `pending` and `needs_update`	also in `ready_for_review`
the response carries `owners` and `verificationFiles`	owners and documents are listed separately

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

Instagram: BlockWyre Instagram
Twitter: BlockWyre Twitter
Facebook: BlockWyre Facebook
LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!

Endpoint

Path parameters​

Request Body Sample​

Request Body Schema​

Response Sample​

Response Schema​

Errors​

Coming from v2​

Support and Resources​

Stay Updated​