Skip to main content
GET
/
v2
/
onboard
/
{refNo}
Retrieve Onboarding Data
curl --request GET \
  --url https://kyc.sbx.moduluslabs.io/v2/onboard/{refNo} \
  --header 'Authorization: Bearer <token>'
{
  "onboardingStatus": "NEW",
  "onboardingReferenceNumber": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "merchantName": "<string>",
  "legalName": "<string>",
  "businessHandle": "<string>",
  "modeOfPayments": [
    "<string>"
  ],
  "currency": "<string>",
  "tin": "<string>",
  "industry": "<string>",
  "serviceDescription": "<string>",
  "isBrickAndMortarStore": true,
  "address": {
    "office": {
      "city": "<string>",
      "line1": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "contactNumber": "<string>",
      "barangay": "<string>",
      "buildingNameAndNumber": "<string>"
    },
    "registered": {
      "city": "<string>",
      "line1": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "contactNumber": "<string>",
      "barangay": "<string>",
      "buildingNameAndNumber": "<string>"
    }
  },
  "representatives": {
    "authorized": {
      "firstName": "<string>",
      "lastName": "<string>",
      "emailAddress": "[email protected]",
      "contactNumber": "<string>",
      "dateOfBirth": "2023-12-25",
      "position": "<string>",
      "middleName": "<string>",
      "tin": "<string>",
      "sss": "<string>",
      "mothersMaidenName": "<string>",
      "gender": "MALE"
    },
    "escalation": {
      "firstName": "<string>",
      "lastName": "<string>",
      "emailAddress": "[email protected]",
      "contactNumber": "<string>",
      "dateOfBirth": "2023-12-25",
      "tin": "<string>",
      "sss": "<string>",
      "position": "<string>"
    }
  },
  "banks": [
    {
      "accountDepositType": "BANK",
      "currency": "PHP",
      "accountType": "SAVINGS",
      "bankName": "<string>",
      "accountName": "<string>",
      "accountNumber": "<string>",
      "preferredSettlementRail": "instapay",
      "bankCode": "<string>"
    }
  ],
  "dateCreated": "2023-11-07T05:31:56Z",
  "dateUpdated": "2023-11-07T05:31:56Z",
  "declinedReason": "<string>"
}

​
Overview

Retrieves the complete onboarding data for a merchant using the onboarding reference number. This endpoint returns all information submitted during the onboarding process, including business details, representatives, bank accounts, and current approval status.
Use case: Check the status of a merchant’s onboarding application and retrieve all submitted information for review or updates.

​
Authentication

This endpoint requires JWT Bearer Token authentication. 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Authorization Required: The authenticated user must be the owner of the onboarding record. Only the user who created the onboarding record can retrieve it.

​
Path Parameters

​
refNo
string
required
The onboarding reference number (UUID v4 format)Format: Valid UUID v4Example: "550e8400-e29b-41d4-a716-446655440000"
This is the referenceNumber returned when you successfully submit an onboarding request via the Onboard Merchant endpoint.

​
Response

​
Success Response

Status Code: 200 OK
​
onboardingStatus
string
required
Current status of the merchant’s onboarding applicationValues:
  • NEW: Merchant completed onboarding, awaiting initial approval
  • PENDING: Merchant updated form after decline, awaiting re-approval
  • APPROVED: Merchant has been approved
  • DECLINED: Merchant was declined and needs to update their form
Example: "NEW"
​
onboardingReferenceNumber
string
required
Unique identifier for the onboarding recordFormat: UUID v4Example: "550e8400-e29b-41d4-a716-446655440000"
​
businessType
string
required
Type of business entityValues: STARTER, SOLE_PROPRIETOR, PARTNERSHIP, CORPORATIONExample: "CORPORATION"
​
legalName
string
Legal registered name of the businessExample: "Acme Corporation Inc."
​
merchantName
string
required
Trading name or DBA (Doing Business As) nameExample: "Acme Store"
​
modeOfPayments
array
required
List of accepted payment modesExample: ["ECOM", "QRPH", "PAYMENT_LINK"]
​
currency
string
required
Primary currency for transactionsExample: "PHP"
​
tin
string
required
Tax Identification NumberExample: "123-456-789-000"
​
industry
string
required
Business industry categoryExample: "Retail"
​
serviceDescription
string
required
Description of services or products offeredExample: "Online retail store selling electronics and gadgets"
​
businessHandle
string
required
Unique business handle/slug for payment linksExample: "acme-store"
​
isBrickAndMortarStore
boolean
required
Whether the business has a physical store locationExample: true
​
address
object
required
Business address information
​
representatives
object
required
Authorized representatives
​
banks
array
required
List of bank accounts for settlement
​
incorporators
array
List of business incorporators (not applicable for STARTER business type)Properties: firstName, middleName, lastName, emailAddress, contactNumber, dateOfBirth, address
​
signatories
array
List of authorized signatoriesProperties: firstName, middleName, lastName, position
​
websites
object
Business online presenceProperties: businessWebsiteUrl, isBusinessWebsiteUnderDevelopment, facebookUrl, twitterUrl, instagramUrl, tiktokUrl
​
dateCreated
string
required
Timestamp when the onboarding record was createdFormat: ISO 8601Example: "2024-01-15T10:30:00Z"
​
dateUpdated
string
Timestamp of the last status updateFormat: ISO 8601Example: "2024-01-20T14:45:00Z"
​
declinedReason
string
Reason for decline (only present when status is DECLINED)Example: "Missing required documents"

​
Error Responses

Status Code: 400
{
  "statusCode": 400,
  "message": "Invalid onboarding reference number format",
  "error": "Bad Request",
  "details": {
    "refNumReceived": "invalid-uuid-format"
  }
}
Cause: The reference number provided is not a valid UUID v4 formatSolution: Ensure the reference number is a valid UUID v4 string
Status Code: 400
{
  "statusCode": 400,
  "message": "Onboarding record does not exist",
  "error": "Bad Request"
}
Cause: No onboarding record found with the provided reference numberSolution: Verify the reference number is correct and the onboarding record exists
Status Code: 400
{
  "statusCode": 400,
  "message": "Onboarding reference number mismatch",
  "error": "Bad Request",
  "details": {
    "refNumReceived": "550e8400-e29b-41d4-a716-446655440000"
  }
}
Cause: The authenticated user is not authorized to access this onboarding recordSolution: Ensure you’re using the correct JWT token for the account that owns this onboarding record
Status Code: 400
{
  "statusCode": 400,
  "message": "Failed to retrieve authorized representatives",
  "error": "Bad Request"
}
Cause: Database error retrieving representative informationSolution: Retry the request. If the issue persists, contact support
Status Code: 401
{
  "statusCode": 401,
  "message": "Account not found",
  "error": "Unauthorized"
}
Cause: Invalid or missing JWT Bearer token, or account associated with token doesn’t existSolution:
  • Verify the Authorization header contains a valid JWT token
  • Ensure the token hasn’t expired
  • Confirm the account exists in the system

​
Code Examples

# Set your Bearer token and reference number
TOKEN="your_jwt_bearer_token_here"
REF_NO="550e8400-e29b-41d4-a716-446655440000"

curl -X GET "https://kyc.sbx.moduluslabs.io/v2/onboard/$REF_NO" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

​
Onboarding Status Flow

1

NEW

Merchant has completed the onboarding form and submitted it for initial review. Awaiting admin approval.
2

DECLINED (Optional)

Admin reviewed the application and declined it. The declinedReason field contains the reason for rejection. Merchant needs to update their information.
3

PENDING (Optional)

Merchant has updated their form after being declined and resubmitted for review. Awaiting admin re-approval.
4

APPROVED

Admin has approved the merchant’s onboarding application. Merchant can now process transactions.

​
Bank Account Masking

Security Feature: Bank account numbers are masked for security based on user roles.
Full account numbers visible to:
  • Super Admins
  • Settlement role users
  • Checker role users
  • The account owner (authenticated user who created the onboarding record)
Other users see: ********1234 (only last 4 digits visible)

​
Use Cases

Check Application Status

Monitor the approval status of your onboarding application

Review Submitted Data

Verify all information submitted during onboarding

Handle Declined Applications

Check the decline reason and prepare updated information

Retrieve for Updates

Get current data before submitting corrections or updates

​
Best Practices

Always save the referenceNumber returned from the Onboard Merchant endpoint. You’ll need it to check status and retrieve data later.
// Save this from onboarding response
const referenceNumber = onboardingResponse.referenceNumber;
// Store in database or secure storage
Implement polling to check for status changes if you need real-time updates:
async function pollOnboardingStatus(refNo) {
  const interval = setInterval(async () => {
    const data = await retrieveOnboardingData(refNo);

    if (data.onboardingStatus === 'APPROVED') {
      console.log(' Onboarding approved!');
      clearInterval(interval);
    } else if (data.onboardingStatus === 'DECLINED') {
      console.log(' Onboarding declined:', data.declinedReason);
      clearInterval(interval);
    }
  }, 60000); // Check every minute
}
Consider implementing exponential backoff for polling to avoid rate limiting.
When status is DECLINED, present the decline reason to the user and guide them to update their information:
if (data.onboardingStatus === 'DECLINED') {
  // Show decline reason to user
  alert(`Application declined: ${data.declinedReason}`);
  // Redirect to update form
  window.location.href = '/update-onboarding';
}
Cache the response to reduce API calls:
const CACHE_TTL = 300000; // 5 minutes
let cachedData = null;
let cacheTimestamp = 0;

async function getCachedOnboardingData(refNo) {
  const now = Date.now();

  if (cachedData && (now - cacheTimestamp) < CACHE_TTL) {
    return cachedData;
  }

  cachedData = await retrieveOnboardingData(refNo);
  cacheTimestamp = now;
  return cachedData;
}

​
Troubleshooting

Error: Onboarding reference number mismatchCause: You’re trying to access an onboarding record that doesn’t belong to your accountSolution:
  • Verify you’re using the correct JWT token for the account that created this onboarding record
  • Each onboarding record can only be accessed by the account that created it
  • Super Admins may need special permissions to access other accounts’ records
Error: Invalid onboarding reference number formatSolution:
  • Ensure the reference number is a valid UUID v4 format
  • Example valid format: 550e8400-e29b-41d4-a716-446655440000
  • Check for extra spaces or incorrect characters
Error: Onboarding record does not existPossible Causes:
  • The reference number is incorrect
  • The onboarding record was deleted
  • You’re using a sandbox reference number in production (or vice versa)
Solution:
  • Double-check the reference number
  • Verify you’re using the correct environment (sandbox vs production)

​
Next Steps

Onboard Merchant

Create a new merchant onboarding record

Create Account

Create an account before onboarding

Authentication Guide

Learn about JWT token authentication

Error Handling

Handle API errors properly

Authorizations

​
Authorization
string
header
required

JWT Bearer token authentication

Path Parameters

​
refNo
string<uuid>
required

The onboarding reference number (UUID v4 format)

Response

Onboarding data retrieved successfully

​
onboardingStatus
enum<string>
Available options:
NEW,
PENDING,
APPROVED,
DECLINED
​
onboardingReferenceNumber
string<uuid>
​
merchantName
string
​
legalName
string
​
businessHandle
string
​
modeOfPayments
string[]
​
currency
string
​
tin
string
​
industry
string
​
serviceDescription
string
​
isBrickAndMortarStore
boolean
​
address
object
​
representatives
object
​
banks
object[]
​
dateCreated
string<date-time>
​
dateUpdated
string<date-time> | null
​
declinedReason
string | null