Retrieve Onboarding Data - Modulus Labs API

# 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"

{
  "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": "jsmith@example.com",
      "contactNumber": "<string>",
      "dateOfBirth": "2023-12-25",
      "position": "<string>",
      "middleName": "<string>",
      "tin": "<string>",
      "sss": "<string>",
      "mothersMaidenName": "<string>"
    },
    "escalation": {
      "firstName": "<string>",
      "lastName": "<string>",
      "emailAddress": "jsmith@example.com",
      "contactNumber": "<string>",
      "dateOfBirth": "2023-12-25",
      "tin": "<string>",
      "sss": "<string>",
      "position": "<string>"
    }
  },
  "banks": [
    {
      "bankName": "<string>",
      "accountName": "<string>",
      "accountNumber": "<string>",
      "bankCode": "<string>"
    }
  ],
  "dateCreated": "2023-11-07T05:31:56Z",
  "dateUpdated": "2023-11-07T05:31:56Z",
  "declinedReason": "<string>"
}

GET

onboard

{refNo}

# 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"

{
  "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": "jsmith@example.com",
      "contactNumber": "<string>",
      "dateOfBirth": "2023-12-25",
      "position": "<string>",
      "middleName": "<string>",
      "tin": "<string>",
      "sss": "<string>",
      "mothersMaidenName": "<string>"
    },
    "escalation": {
      "firstName": "<string>",
      "lastName": "<string>",
      "emailAddress": "jsmith@example.com",
      "contactNumber": "<string>",
      "dateOfBirth": "2023-12-25",
      "tin": "<string>",
      "sss": "<string>",
      "position": "<string>"
    }
  },
  "banks": [
    {
      "bankName": "<string>",
      "accountName": "<string>",
      "accountNumber": "<string>",
      "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

Show Address Properties

address.office

object

required

Main office location with contact numberProperties: city, line1, buildingNameAndNumber, state, postalCode, barangay, contactNumber

address.registered

object

Registered business address (if different from office)Properties: city, line1, buildingNameAndNumber, state, postalCode, barangay, contactNumber

representatives

object

required

Authorized representatives

Show Representatives Properties

representatives.authorized

object

required

Primary authorized representativeProperties: firstName, middleName, lastName, emailAddress, contactNumber, dateOfBirth, tin, sss, position, mothersMaidenName, gender

representatives.escalation

object

Escalation contact (optional)Properties: firstName, middleName, lastName, emailAddress, contactNumber, dateOfBirth, tin, sss, position

banks

array

required

List of bank accounts for settlement

Show Bank Account Properties

banks[].accountDepositType

string

required

Type of deposit account: BANK, GCASH, PAYMAYA, NO_ACCOUNT

banks[].bankName

string

Name of the bank

banks[].accountName

string

Name on the bank account

banks[].accountNumber

string

Bank account number

Security Note: Account numbers may be masked (showing only last 4 digits) depending on user role. Full numbers visible to Super Admins, Settlement, Checker roles, and account owner.

banks[].currency

string

Currency of the bank account

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

400 Bad Request - Invalid Reference Number Format

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

400 Bad Request - Record Does Not Exist

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

400 Bad Request - Reference Number Mismatch

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

400 Bad Request - Failed to Retrieve Representatives

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

401 Unauthorized

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

# 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

NEW

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

DECLINED (Optional)

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

PENDING (Optional)

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

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

Save the Reference Number

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

Poll for Status Updates

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.

Handle Declined Applications

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 Response Data

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

Reference Number Mismatch Error

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

Invalid UUID Format

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

Record Not Found

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

Show child attributes

representatives

object

Show child attributes

banks

object[]

Show child attributes

dateCreated

string<date-time>

dateUpdated

string<date-time> | null

declinedReason

string | null

Onboard Merchant Retrieve Onboarding Status

⌘I

​Overview

​Authentication

​Path Parameters

​Response

​Success Response

​Error Responses

​Onboarding Status Flow

​Bank Account Masking

​Use Cases

Check Application Status

Review Submitted Data

Handle Declined Applications

Retrieve for Updates

​Best Practices

​Troubleshooting

​Next Steps

Onboard Merchant

Create Account

Authentication Guide

Error Handling

Authorizations

Path Parameters

Response

Overview

Authentication

Path Parameters

Response

Success Response

Error Responses

Onboarding Status Flow

Bank Account Masking

Use Cases

Best Practices

Troubleshooting

Next Steps