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?states={state1}&states={state2}&formId={formId}

formId is optional. Leave it out to list submissions across every active KYC form and all its versions:

GET {base_url}/ExtForm/submissions?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	No	The form to retrieve submissions for. Omit it to list submissions across every active KYC form and all its versions; each submission then includes its formId. Submissions on deleted forms are only returned when their formId is passed. Sending formId with an empty value returns 400: leave the parameter out instead. See Form versions
states	array of strings	Query	Yes	List of KYC state values to filter submissions by (can be specified multiple times). If omitted, no submissions are returned (an empty list, not an error)

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

This example is for a request with a formId. When you omit formId, each submission also includes the formId of the form version it was started on. See List submissions across all form versions.

{
  "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
submissions[].formId	The form version the submission is on. Only returned when formId was not passed — pass it to Get Session ID to continue that customer's KYC

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'

List submissions across all form versions

Omit formId to cover every version of your KYC forms. Each submission then includes the formId of the version it was started on.

curl -X GET \
  '{base_url}/ExtForm/submissions?states=New&states=Onboarding&states=ComplianceReview' \
  -H 'Authorization: Bearer your_token_here'

{
  "statusCode": 200,
  "messages": ["Processed successfully"],
  "result": {
    "count": 2,
    "submissions": [
      {
        "submissionId": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "customerId": "c3d4e5f6-7a8b-4c9d-8e0f-2a3b4c5d6e7f",
        "customerName": "John Smith",
        "submissionDate": "2026-09-18T10:02:11Z",
        "kycState": "New",
        "email": "john.smith@example.com",
        "formId": "7ac9ab5e-4123-4456-b8c3-123456789012"
      },
      {
        "submissionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "customerId": "c3d4e5f6-7a8b-4c9d-8e0f-2a3b4c5d6e7f",
        "customerName": "John Smith",
        "submissionDate": "2026-02-10T08:15:40Z",
        "kycState": "ComplianceReview",
        "email": "john.smith@example.com",
        "formId": "5d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a"
      }
    ]
  }
}

Here the same customer has two KYCs: the original one in ComplianceReview on an older form version, and an empty one in New on the current version. Results are newest first, so choose the KYC to continue by kycState, not by position, then pass its formId to Get Session ID. See Form versions.

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	formId cannot be empty; omit it to cover every KYC form	formId was sent with an empty value: pass a form ID, or leave the parameter out
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. With a formId, only that exact form version is covered: customers who onboarded on an older version are not included. Omit formId to cover all versions. Without a formId the whole tenant is returned in one response (there is no paging), so prefer Search Submissions by email to look up a single customer.
2. At least one state must be specified in the states parameter; without it the response is an empty list.
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