Submit KYC Details

Writes the applicant's details onto the customer's verification record. It does not change the status and does not start verification: request it when the details and documents are in.

This is a whole-applicant write, not a merge: every field lands on the record, and a field you leave out is cleared. Send the full set each time. Every field is optional here; Request Verification is where first_name, last_name, date_of_birth, identity_document.number and identity_document.type become required.

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

Replaces, with Open KYC Record, POST /api/v2/kyc/banking-verification/individual.

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}/kyc

Path parameters

Parameter	Type	Description
`customer_id`	string (`cst_…`)	Required. The customer. Its record must be open and `pending` or `needs_update`.

Request Body Sample

{
  "email": "samantha@example.com",
  "first_name": "Samantha",
  "last_name": "Reyes",
  "phone": "+14155550123",
  "date_of_birth": "1990-04-12",
  "nationality": "US",
  "address": {
    "line1": "742 Evergreen Terrace",
    "line2": "Apt 2",
    "city": "Springfield",
    "state": "OR",
    "postal_code": "97477",
    "country": "US"
  },
  "identity_document": {
    "number": "X1234567",
    "type": "passport",
    "issue_date": "2018-03-01",
    "expiry_date": "2028-03-01",
    "country_of_issue": "US"
  },
  "occupation": "Engineer",
  "employed_company_name": "Northwind Traders",
  "employed_job_title": "Staff Engineer",
  "source_of_funds": ["salary"]
}

Request Body Schema

Field	Type	Description
`email`	string	A valid email.
`first_name`	string	At most 255 characters.
`last_name`	string	At most 255 characters.
`phone`	string	E.164, e.g. `+14155550123`.
`date_of_birth`	string	`YYYY-MM-DD`.
`nationality`	string	ISO 3166-1 alpha-2, e.g. `US`.
`address`	object	The residential address. Either omitted, or with `line1`, `city`, `state`, `postal_code` and `country` all filled in.
`address.line1`	string	At most 255 characters.
`address.line2`	string	Optional. At most 255 characters.
`address.city`	string	At most 100 characters.
`address.state`	string	At most 100 characters.
`address.postal_code`	string	A valid postal code for `address.country`.
`address.country`	string	ISO 3166-1 alpha-2.
`identity_document`	object	The government identity document. Either omitted, or with at least `number` and `type`.
`identity_document.number`	string	2 to 20 characters.
`identity_document.type`	string	`passport`, `driver_license`, `national_id`, `ssn`, `itin`, `ein` or `other`.
`identity_document.issue_date`	string	Optional. `YYYY-MM-DD`.
`identity_document.expiry_date`	string	Optional. `YYYY-MM-DD`.
`identity_document.country_of_issue`	string	Optional. ISO 3166-1 alpha-2.
`occupation`	string	At most 255 characters.
`employed_company_name`	string	At most 255 characters.
`employed_job_title`	string	At most 255 characters.
`source_of_funds`	array of string	Any of `salary`, `savings`, `investments`, `loans`, `self_employed`, `other`.

Response Sample

The record with the details written. ready turns true once the fields a provider needs are in.

{
  "id": "kyc_01k8x494z0e2escqpt6bde8hag",
  "customer_id": "cst_01k8x40x9gfx6sv8a99hswy9bd",
  "type": "banking",
  "status": "pending",
  "status_reason": "verification record created",
  "email": "samantha@example.com",
  "first_name": "Samantha",
  "last_name": "Reyes",
  "phone": "+14155550123",
  "date_of_birth": "1990-04-12",
  "nationality": "US",
  "address": {
    "line1": "742 Evergreen Terrace",
    "line2": "Apt 2",
    "city": "Springfield",
    "state": "OR",
    "postal_code": "97477",
    "country": "US"
  },
  "identity_document": {
    "number": "X1234567",
    "type": "passport",
    "issue_date": "2018-03-01",
    "expiry_date": "2028-03-01",
    "country_of_issue": "US"
  },
  "occupation": "Engineer",
  "employed_company_name": "Northwind Traders",
  "employed_job_title": "Staff Engineer",
  "source_of_funds": ["salary"],
  "ready": true,
  "event_history": [
    {
      "status": "pending",
      "status_reason": "verification record created",
      "date": "2025-10-31T12:36:04Z"
    }
  ],
  "created_at": "2025-10-31T12:36:04Z",
  "updated_at": "2025-10-31T12:36:04Z"
}

Response Schema

See Open KYC Record.

Errors

Status	`message`	When
`400`	`invalid_address`	`address` is partly filled in: `line1`, `city`, `state` or `postal_code` is missing.
`400`	`invalid_country`	`address` is filled in without a `country`.
`400`	`invalid_id_number`	`identity_document` is filled in without a `number`.
`400`	`invalid_id_document_type`	`identity_document` has a `number` but no `type`.
`400`	`failed to parse request`	The body is not valid JSON, `identity_document.type` or a `source_of_funds` entry is not one of its values, or `customer_id` is not a `cst_…` TypeID.
`401`	`unauthorized`	Missing or invalid signature, or the caller is an account-scoped key or a customer session.
`403`	`forbidden`	A dashboard member whose role does not allow this. A workspace-scoped key always may.
`404`	`kyc_not_found`	The customer has no record: open one first.
`409`	`kyc_verification_in_flight`	The record is `in_review`: the provider is looking at it.
`409`	`kyc_already_approved`	The record is `approved`.
`409`	`kyc_rejected`	The record is `rejected`.
`422`	`Validation failed`	A value breaks its format or length (email, phone, a date, a country, a postal code, an id number); `details` names it.

Coming from v2

v2 (`POST /api/v2/kyc/banking-verification/individual`)	v3
`accountId` in the body	`customer_id` in the path, on a record opened first
`dateOfBirth`, `phone`, `address` required here	all optional here; required fields are checked at Request Verification
a left-out field keeps its old value	a left-out field is cleared
`documentId.idNumber`, `idDocumentType`, `idIssueDate`, `idExpiryDate`, `idCountryOfIssue`	`identity_document.number`, `type`, `issue_date`, `expiry_date`, `country_of_issue`
`documentId.nationality`	`nationality` (top-level)
`address.address1`, `address2`, `postalCode`	`address.line1`, `line2`, `postal_code`
response `{ accountId, verificationUrl }`	the whole record; no verification link
none	`email`, `first_name`, `last_name`, `occupation`, `employed_company_name`, `employed_job_title`, `source_of_funds`

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​