Skip to main content

Get Application KYC Status

Overview​

The Get Application KYC Status API retrieves the stored KYC verification result for a specific application. This endpoint returns the provider applicant ID, the SpeedyDD-mapped status, and any stored document URLs from the identity verification process.

Authentication​

This endpoint requires authentication. See API Authentication for detailed requirements and how to obtain credentials.

Endpoint​

GET /api/applications/{applicationID}/kyc/status

Path Parameters​

  • applicationID (required): The unique identifier of the application to query

Request Body​

This API does not require a request body.

Response Structure​

Interface Definitions​

interface KYCStatusResponse {
   statusCode: number;
   data: {
      applicantId: string;
      status: KYCStatus;
      documents: string[];
   };
}

enum KYCStatus {
   PENDING = 'pending',
   APPROVED = 'approved',
   REJECTED = 'rejected',
   EXPIRED = 'expired',
}

Success Response​

{
   "statusCode": 200,
   "data": {
      "applicantId": "68edee456a03b3a57aff8040",
      "status": "approved",
      "documents": [
         "https://storage.googleapis.com/.../68edeec72b4be3e76f77529d.jpeg?sig=...",
         "https://storage.googleapis.com/.../68edeec72b4be3e76f7752a0.jpeg?sig=..."
      ]
   }
}

Error Response​

{
   "statusCode": 404,
   "message": "KYC result not found",
   "errors": [
      {
         "field": "applicationID",
         "message": "No KYC result exists for this application"
      }
   ]
}

Status Mapping​

The system maps provider statuses to standardized SpeedyDD values:

Provider StatusSpeedyDD StatusDescription
initpendingKYC process initiated but not completed
completedapprovedIdentity verification successful
declinedrejectedIdentity verification failed
expiredexpiredSession or verification expired

Field Descriptions​

  • applicantId: The unique identifier from the identity provider (e.g., Sumsub)
  • status: The current verification status using SpeedyDD standardized values
  • documents: Array of signed, time-limited URLs to verification artifacts

Usage Guidelines​

When to Use This API​

  • Status Monitoring: Check verification progress after initiating KYC
  • Completion Verification: Confirm successful identity verification
  • Document Access: Retrieve verification documents for compliance
  • Workflow Integration: Integrate KYC status into application processing

Integration Workflow​

  1. Start KYC: Use Start KYC API to initiate verification
  2. Monitor Progress: Periodically call this endpoint to check status
  3. Handle Completion: Process results when status becomes approved or rejected
  4. Document Storage: Optionally download and store documents locally

Field Validation Requirements​

  • applicationID must be a valid application identifier
  • Application must exist in the system
  • User must have permissions to access the KYC status
  • KYC process must have been initiated for the application
Integration Tip

Consider implementing webhook notifications for real-time status updates instead of polling this endpoint frequently.

Important

Document URLs are time-limited and should be accessed promptly. Store documents locally if long-term access is required.