Submit External Verification

For an applicant you already verified with your own identity provider (Sumsub, Jumio, Onfido, your own stack). It records which provider it was and its raw result on the customer's verification record, then hands the record to the verification provider exactly as Request Verification does.

It does not approve the record: the record goes in_review, and the provider decides. The same checks apply: the applicant's required details, and confirmed face and document-front documents. This call carries no files: upload the documents first, through Presign and Complete.

Requesting again while the record is in_review or approved answers 200 with already_running: true and records nothing.

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

Replaces POST /api/v2/kyc/banking-verification/individual/{accountId}/submit-external-verification.

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

POST

/v3/customers/{customer_id}/kyc/submit-external-verification

Path parameters

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

Request Body Sample

{
  "provider": "sumsub",
  "raw": {
    "applicantId": "abc123",
    "reviewResult": "GREEN"
  }
}

Request Body Schema

Field	Type	Description
provider	string	Required. Your identity provider's name. Free text, trimmed; longer than 60 characters is cut to 60.
raw	object, array or string	Required. Your provider's result, stored as sent. A JSON object or array, or a string holding one ("{\"applicantId\":\"abc123\"}").

Response Sample

{
  "kyc": {
    "id": "kyc_01k8x494z0e2escqpt6bde8hag",
    "customer_id": "cst_01k8x40x9gfx6sv8a99hswy9bd",
    "type": "banking",
    "status": "in_review",
    "status_reason": "verification requested",
    "first_name": "Samantha",
    "last_name": "Reyes",
    "date_of_birth": "1990-04-12",
    "identity_document": {
      "number": "X1234567",
      "type": "passport"
    },
    "ready": true,
    "event_history": [
      {
        "status": "in_review",
        "status_reason": "verification requested",
        "date": "2025-10-31T12:47:10Z"
      },
      {
        "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:47:10Z"
  },
  "already_running": false
}

Response Schema

Same as Request Verification.

Errors

Status	message	When
400	invalid_external_provider	provider is blank.
400	invalid_external_raw	raw is not a JSON object or array (or a string holding one).
400	failed to parse request	The body is not valid JSON, 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_needs_update	The record is needs_update.
409	kyc_rejected	The record is rejected.
422	Validation failed	provider or raw is missing; details names it.
422	kyc_incomplete_applicant	A required applicant field is missing.
422	kyc_missing_documents	The face or document-front document is missing or not completed. The provider and result are kept: upload the documents and send the request again.
422	kyc_business_not_supported	The customer is a business.

Coming from v2

v2 (POST …/individual/{accountId}/submit-external-verification)	v3
multipart/form-data with face, documentFront, documentBack files	JSON; files uploaded beforehand to the face, document-front and document-back slots
raw (JSON string), provider	the same names; raw may also be sent as a JSON object
status set to approved directly	status in_review; the provider decides
409 when approved or in_review	200 with already_running: true
response: the full record	{ kyc, already_running }

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!