Skip to main content

Simulate v5 Onboarding Status

Use the Simulate v5 Onboarding API to transition a customer's status and sub-status during sandbox testing. This lets you reproduce compliance scenarios—such as RFI requests, KYC submission, approvals, and rejections—without waiting for Nium's compliance team to act.

note

This API is available in sandbox only. It has no effect in production environments.

API reference​

POST /api/v5/simulations/onboard/{customerHashId}/transition

Base URL (Sandbox): https://gatewaysandbox.nium.com

See the v1 simulation API for the previous-version equivalent.

Request headers​

HeaderTypeDescription
x-api-keystringAPI key for authentication.
x-client-namestring (≤32 chars)Client name, required on every request.
x-request-idUUID (36 chars)Unique request identifier; required on every call.
Content-TypestringMust be application/json.

Path parameters​

ParameterTypeDescription
customerHashIdUUIDUnique identifier for the customer, generated during onboarding. The customer must be onboarded as a v5 customer.

Request body​

FieldTypeRequiredDescription
nextActionstringYesThe action to simulate. See Supported actions for allowed values and state prerequisites.
requestInfoForobjectConditionalRequired when nextAction is raise_rfi. Specifies the document or field to request. See requestInfoFor object.
isResubmissionAllowedbooleanOptionalOnly applicable when nextAction is reject. When false, the customer cannot resubmit their application. Defaults to true.

Supported actions​

nextActionPrerequisite stateExpected outcomeResponse message
submit_kycsubStatus = awaiting_kycCustomer moves out of awaiting_kyc to rfi_requested, null, or under_review.KYC submitted successfully.
raise_rfisubStatus = under_review, null, or rfi_requestedsubStatus updates to rfi_requested. Fetch RFI details to see the requested field.RFI Raised Successfully.
clearstatus = pending or errorstatus updates to clear.Status updated successfully.
rejectstatus = pending or errorstatus updates to rejected. The isResubmissionAllowed flag is set as specified.Status updated successfully.

requestInfoFor object​

Required when nextAction is raise_rfi. The object shape differs by customer type.

Individual customer

FieldTypeDescription
customerTypestringMust be individual.
requeststringDocument or field to request. Allowed values: passport, bankStatement, firstName, lastName, dateOfBirth, driversLicence.

Corporate customer

FieldTypeDescription
customerTypestringMust be corporate.
requeststringDocument or field to request. Allowed values: applicant_Address, applicant_Identity, stakeholder_Address, stakeholder_Identity, businessRegistrationDocument, corporateAddressProof.

Sample requests​

Submit KYC​

Transitions a customer out of awaiting_kyc.

{
  "nextAction": "submit_kyc"
}

Raise RFI — individual customer​

Transitions subStatus to rfi_requested and flags that the customer's first name is required.

{
  "nextAction": "raise_rfi",
  "requestInfoFor": {
    "customerType": "individual",
    "request": "firstName"
  }
}

Raise RFI — corporate customer​

Transitions subStatus to rfi_requested and requests an applicant identity document.

{
  "nextAction": "raise_rfi",
  "requestInfoFor": {
    "customerType": "corporate",
    "request": "applicant_Identity"
  }
}

Raise RFI — minimal (no document specified)​

{
  "nextAction": "raise_rfi"
}

Clear (approve)​

Transitions status to clear.

{
  "nextAction": "clear"
}

Reject — resubmission allowed​

{
  "nextAction": "reject"
}

Reject — resubmission not allowed​

{
  "nextAction": "reject",
  "isResubmissionAllowed": false
}

Responses​

200 — Success​

The action was applied. The customer's status or subStatus is updated and a webhook is dispatched to the configured callback URL.

{
  "message": "RFI Raised Successfully."
}

Possible messages correspond to the action performed:

nextActionmessage
submit_kycKYC submitted successfully.
raise_rfiRFI Raised Successfully.
clearStatus updated successfully.
rejectStatus updated successfully.

404 — Customer not found or not a v5 customer​

// Customer not found
{
  "errors": [
    {
      "code": "sim_invalid_customer_hash_id",
      "description": "Customer Not found with customerHashId - {customerHashId}"
    }
  ]
}

// Customer exists but was not onboarded as v5
{
  "errors": [
    {
      "code": "sim_customer_not_v5",
      "description": "Customer with customerHashId - {customerHashId} is not onboarded as a v5 customer"
    }
  ]
}

422 — Invalid action for current state​

Returned when the requested nextAction is not allowed from the customer's current status or subStatus.

{
  "errors": [
    {
      "code": "sim_invalid_next_action",
      "description": "Current status - 'pending'/subStatus - 'awaiting_kyc' doesn't allow action 'raise_rfi'. Allowed action from current state: submit_kyc."
    }
  ]
}