Get Submissions

The Get Submissions API allows you to retrieve a list of submissions for a specific form, filtered by KYC state. This is useful for tracking customer progress, monitoring submission statuses, and managing the onboarding process.

API Endpoint

GET {base_url}/ExtForm/submissions?formId={formId}&states={state1}&states={state2}

Request Format

This endpoint accepts a GET request with query parameters for filtering.

Request Parameters

Parameter	Type	Location	Required	Description
formId	string	Query	Yes	The unique identifier of the form to retrieve submissions for
states	array of strings	Query	Yes	List of KYC state values to filter submissions by (can be specified multiple times)

Valid KYC State Values

The states parameter can include one or more of the following values from the KycStateEnum:

Value	Display Name	Description
New	New	Initial state for newly created submissions
Onboarding	Onboarding	Customer is in the process of completing their submission
ComplianceReview	Compliance Review	Submission is under review by the compliance team
Approved	Approved	Submission has been approved
Rejected	Rejected	Submission has been rejected
OnboardingAfterRejection	Onboarding After Rejection	Customer is updating their submission after a previous rejection

The state values in the request should match the enum names exactly (e.g., "New", "Onboarding", "ComplianceReview").

Request Headers

Content-Type: application/json
Authorization: Bearer {token}

Response Format

{
  "statusCode": 200,
  "messages": ["Processed successfully"],
  "result": {
    "count": 2,
    "submissions": [
      {
        "submissionId": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
        "customerId": "cust-12345",
        "customerName": "John Smith",
        "submissionDate": "2023-05-15T14:30:45Z",
        "kycState": "Onboarding",
        "email": "john.smith@example.com"
      },
      {
        "submissionId": "b2c3d4e5-6f7g-8h9i-0j1k-l2m3n4o5p6q7",
        "customerId": "cust-67890",
        "customerName": "Sarah Johnson",
        "submissionDate": "2023-05-16T09:15:30Z",
        "kycState": "Approved",
        "email": "sarah.johnson@example.com"
      }
    ]
  }
}

Response Fields

Field	Description
count	Total number of submissions returned
submissions	Array of submission objects
submissions[].submissionId	Unique identifier for the submission
submissions[].customerId	Unique identifier for the customer
submissions[].customerName	Full name of the customer
submissions[].submissionDate	Date and time when the submission was created
submissions[].kycState	Current KYC state of the submission
submissions[].email	Email address of the customer associated with the submission

Example Usage

cURL Example

curl -X GET \
  '{base_url}/ExtForm/submissions?formId=7ac9ab5e-4123-4456-b8c3-123456789012&states=New&states=Onboarding' \
  -H 'Authorization: Bearer your_token_here'

Error Handling

Status Code	Description	Solution
400	Invalid form ID or state values	Check that the form ID is correctly formatted and state values are valid enum names
400	"Make sure to pass proper State"	Ensure state values exactly match the KycStateEnum names (e.g., "New", "Onboarding")
401	Unauthorized	Verify your authentication token
403	Forbidden	Check that your account has permission to access this form's submissions
404	Form not found	Verify that the form ID exists
500	Internal server error	Contact support with the error details

Important Notes

1. This API returns submissions for the specified form based on the provided filters.
2. At least one state must be specified in the states parameter.
3. Invalid state values will result in a validation exception.
4. The submission IDs returned can be used to retrieve more detailed information about each submission.

Use Cases

• Submission tracking: Monitor the progress of customer submissions through the KYC process
• Status management: Identify submissions in specific states for follow-up actions
• Workflow automation: Build automated processes based on submission states
• Customer support: Quickly locate customer submissions to provide support
• Analytics: Track submission counts and progression rates through different KYC states

Workflow Integration

The Get Submissions API is typically used in the following workflow:

1. Call the Get Forms API to retrieve available forms
2. Use the Get Submissions API to retrieve submissions for specific forms, filtered by state
3. Process the submission data according to your application requirements
4. Use the submission IDs to access more detailed information when needed

Related Resources

• Get Forms API - Retrieving available forms
• Save Submission API - Submitting form answers
• Session Management API - Creating and managing form sessions