Synchronous API

OneView exposes one synchronous machine-execution route pattern:

POST /api/verifications/{subModule}

Released KYC Sub-modules include these stable endpoints:

POST /api/verifications/bvn
POST /api/verifications/nin
POST /api/verifications/pep
POST /api/verifications/sanction

PEP Screening and Sanction Screening are independent requests. Calling one endpoint never calls the other.

The installed OneView version must support an adapter before an adapter-backed Sub-module has usable input fields. Prembly BVN Basic, BVN Advanced, NIN Basic, and NIN Advanced are documented on their Sub-module pages. The separate PEP Screening and Sanction Screening pages document their approved name-search contracts. Always use the input contract documented for the selected released service.

This API is for external client applications. A signed-in administrator with verifications:execute can instead use New Verification on the required Sub-module's Verification page. The Sub-module is already selected; the administrator chooses a Vendor connection, optionally completes Purpose, completes the service fields, and selects Run verification. The same drawer shows Verification completed, normalized status, and Normalized result in a read-only structured JSON view. Do not copy a browser session into an external integration.

Authentication and permission

A client administrator must create an active API Service Account before an external application calls a verification endpoint. Open Settings → API Service Accounts, select Create API Service Account, enter a name, and choose an optional expiration.

A client-owned application or workflow authenticates with an API Service Account key:

Authorization: Bearer <service-account-api-key>

An active credential can call all public integration APIs made available by the installed licensed Modules and Sub-modules. Do not use browser cookies or a human password for machine calls. API Service Accounts cannot use dashboard, setup, administration, user, role, branding, network, license, software-update, or credential-management endpoints.

Before sending production identity data, document the approved purpose, lawful basis, minimum required fields, provider relationship, retention, and access path. See Data boundary & responsibilities.

Request

Use HTTPS and send:

POST /api/verifications/<licensed-sub-module-key>
Authorization: Bearer <service-account-api-key>
Idempotency-Key: sandbox-run:00000001
Content-Type: application/json

{
  "connectionId": "<active-connection-id>",
  "data": {
    "<service-documented-field>": "<provider-approved-synthetic-value>"
  }
}

The path Sub-module key must begin with a lowercase letter and may contain lowercase letters, digits, ., _, or -, up to 64 characters in total. Use the exact Sub-module key licensed and supported by the installed adapter.

The top-level JSON object accepts:

• data — required object containing the selected service's verification fields;
• purpose — optional free text explaining the approved reason for the verification; and
• connectionId — optional ID of a specific active connection for that Sub-module.

Omitting purpose or sending it blank means no purpose is recorded. When supplied, OneView trims it before validation. The normalized value must contain 3–240 Unicode characters and no control characters. Keep it concise and operational, for example Customer onboarding identity check. Do not put a BVN, NIN, name, phone number, address, or other identity or KYC data in it.

When connectionId is omitted, OneView selects the preferred active production connection for the requested Sub-module. Supply connectionId when using a sandbox connection or a specific vendor service. A connection that is inactive, belongs to another Sub-module, or is unavailable for the installed version is rejected.

The request body accepts only connectionId, purpose, and data. Its limit is 1 MiB, but a service can impose substantially smaller field limits. Unknown top-level fields and malformed JSON structures are rejected.

Never place NIN, BVN, a name, address, phone number, date of birth, image, biometric, vendor credential, or other personal/secret data in the URL, idempotency key, logs, metrics, screenshots, or support tickets.

Idempotency

Idempotency-Key is optional but recommended for network retry safety. When supplied, it must be 8–128 characters and contain only letters, digits, ., _, :, or -. Generate it from an operation identifier that contains no personal data, for example sandbox-run:00000001.

Omitting the header always creates a fresh verification and vendor request. Do not omit it when the client application may retry after a timeout or lost response.

A supplied key protects the exact verification request for that API Service Account and Sub-module. Repeating the same key with the same connectionId, normalized purpose, and data returns the earlier verification without another vendor call. An absent purpose and a supplied purpose are different requests. Adding, removing, or changing purpose—or changing the connection or data—while reusing the key is rejected with an HTTP 409 conflict. Never reuse a key for another subject or intended operation.

After a 502, 504, or uncertain network outcome, repeat the same key and exact request. Do not generate a new key to force a retry unless the provider contract supplies a reconciliation procedure that rules out duplicate chargeable work.

Successful response

A completed request returns 200 OK, including verified and not_verified business outcomes:

{
  "status": true,
  "message": "Verification completed",
  "data": {
    "verification": {
      "id": "00000000-0000-4000-8000-000000000000",
      "moduleKey": "<licensed-module-key>",
      "subModuleKey": "<licensed-sub-module-key>",
      "status": "verified",
      "result": {
        "<adapter-normalized-result-field>": "<synthetic-result>"
      },
      "createdAt": "2099-01-01T00:00:00.000Z",
      "completedAt": "2099-01-01T00:00:01.000Z"
    }
  }
}

When the request supplies a non-blank purpose, the verification object includes a non-null purpose. A failed verification includes a non-null safe errorCode; successful outcomes omit it. result and completedAt appear only when meaningful and non-null. Exact normalized result fields are service-specific and may contain personal data, so do not log or share the complete response. When supplied, purpose records why the client initiated the request; it does not by itself establish a lawful basis or provider approval.

Errors

Failures use the standard envelope:

{
  "status": false,
  "statusCode": 504,
  "message": "The vendor verification request timed out",
  "code": "VENDOR_REQUEST_TIMEOUT"
}

Current route failures include:

An adapter/provider failure is stored locally as failed with its safe error code. Review permitted local verification history and client-owned logs; do not expect raw provider errors in the HTTP response.

Reusing an Idempotency-Key after adding, removing, or changing normalized purpose, or after changing connectionId or data, returns an HTTP 409 conflict. Send the original request unchanged for a retry, or use a new key only for a genuinely new verification.

Connection runtime controls

Runtime policy is scoped to each vendor connection. Unless a released adapter declares stricter settings, the current single-server defaults are:

• 60 outbound attempts in a rolling 60-second window;
• four concurrent logical verifications; and
• a circuit that opens for 30 seconds after five consecutive logical failures, followed by a bounded recovery probe.

Each outbound attempt consumes a rate slot. Concurrency and circuit limits apply to the whole logical verification, including any permitted retry.

Automatic retry is off by default. A released adapter can permit two or three total attempts only when its reviewed contract explicitly declares replay with the same OneView correlation/idempotency context safe. Only failures the adapter classifies as retryable are retried; validation failures, business outcomes, unknown failures, and most 4xx responses are not. Backoff is at most one second.

The adapter execution, all outbound attempts, and retry backoff share one 15-second total deadline. It is not a 15-second allowance per attempt. Expiry aborts the execution and returns 504 VENDOR_REQUEST_TIMEOUT. Authentication, validation, licensing, persistence, and HTTP/network overhead occur outside that execution timer, so callers should still use a bounded HTTP timeout modestly greater than 15 seconds.

Usage and activity boundaries

A new logical verification uses one licensed execution. Adapter-approved retries do not use additional licensed executions, although the provider may count attempts according to its own contract.

An idempotent replay returns the existing result without a new provider call. Callers must not infer the provider's billing outcome from a OneView HTTP status; reconcile uncertain requests with the provider when required.

Activity history records the verification identifier, outcome, and safe reason code. It does not display credentials, provider errors, or request/result data.

Synchronous behavior

Execution is synchronous. A request returns the completed result or a safe error in the same HTTP exchange. There is no asynchronous submission, job-status, callback, webhook, polling, or cancellation API in the current release.