Search Submissions

The Search Submissions API allows you to search for submissions within a specific form using field-level filters. This is useful for finding submissions by specific field values such as email, expiry date, or any other form field.

API Endpoint

POST {base_url}/ExtForm/submissions/search

Request Format

This endpoint accepts a POST request with a JSON body containing an optional form ID, optional state filters, and optional field-level filters. Without a form ID, every KYC form (all versions) is searched; field-level filters still require one.

Request Headers

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

Request Body

{
  "formId": "7ac9ab5e-4123-4456-b8c3-123456789012",
  "states": ["Onboarding", "Approved"],
  "email": "john@example.com",
  "filters": [
    {
      "fieldId": "field-id-for-expiry-date",
      "value": "2026-02-01",
      "operator": "GreaterThanOrEqual"
    }
  ]
}

Request Body Fields

Field	Type	Required	Description
formId	string	No	The form to search. Omit it to search every active KYC form and all its versions; each submission then includes its formId. Required when filters are used, since field IDs belong to one form version. An empty string returns 400: leave the field out (or send null) instead. See Form versions
states	array of strings	No	List of KYC state values to filter by. If omitted, all states are included
email	string	No	Filter submissions by customer email (case-insensitive exact match; surrounding spaces are ignored and % / _ are matched literally, not as wildcards). Matches against the email from the customer profile (UserDetails for individuals, Company for legal entities)
filters	array of objects	No	List of field-level filters. All filters are combined with AND logic

Filter Object

Field	Type	Required	Description
fieldId	string	Yes	The unique identifier of the field to filter on. Use the Get Form Fields API to retrieve field IDs
value	string	Yes	The value to compare against
operator	string	No	The comparison operator. Defaults to Equals

Filter Operators

Operator	Description	Example Use Case
Equals	Exact match (default)	Find a submission where email is exactly "john@example.com"
Contains	Partial text match (case-sensitive)	Find submissions where name contains "John"
LessThan	Value is strictly less than the filter value	Find submissions where amount is less than "5000"
GreaterThan	Value is strictly greater than the filter value	Find submissions where expiry date is after "2026-02-01"
LessThanOrEqual	Value is less than or equal to the filter value	Find submissions expiring on or before "2026-03-01"
GreaterThanOrEqual	Value is greater than or equal to the filter value	Find submissions with amount at least "1000"

Supported Field Types for Filtering

The following answer model field types can be used in filters. Click the links to see the full answer model documentation.

Field Type	Supported Operators	Value Format	Example
Text	Equals, Contains	Plain string	"john@example.com"
Text Area	Equals, Contains	Plain string	"some description"
Date Picker	Equals, LessThan, GreaterThan, LessThanOrEqual, GreaterThanOrEqual	ISO date (yyyy-MM-dd)	"2026-02-01"
Numeric	Equals, LessThan, GreaterThan, LessThanOrEqual, GreaterThanOrEqual	Decimal number as string	"1500.50"

Limitation

RichTextBox fields cannot be filtered. RichTextBox is a display-only content field and does not store a searchable answer value, so it is not a supported filter type. Attempting to filter on a RichTextBox field returns a 400 error (Filtering is not supported for field type: RichTextBox).

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

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 Find a customer's KYC on any form version.

{
  "statusCode": 200,
  "messages": ["Processed successfully"],
  "result": {
    "count": 1,
    "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",
        "matchedValues": {
          "field-id-for-email": "john.smith@example.com",
          "field-id-for-expiry-date": "2026-02-15"
        }
      }
    ]
  }
}

Response Fields

Field	Description
count	Total number of submissions matching the filters
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[].matchedValues	Dictionary of field ID to actual stored value for each filtered field. Only present when filters are provided. Date values are formatted as yyyy-MM-dd, numeric values as decimal strings
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

Find a customer's KYC on any form version

Omit formId to find which form version a customer onboarded on. Each result includes formId, which you can pass to Get Session ID to continue that KYC.

Choose by kycState, not by position

Results are ordered newest first. A customer can have more than one KYC, for example an older one in ComplianceReview and a newer, empty one in New that was opened on a later form version. Taking the first result would continue the empty one. Pick the submission to continue by its kycState (and submissionDate), then pass its formId to Get Session ID.

curl -X POST \
  '{base_url}/ExtForm/submissions/search' \
  -H 'Authorization: Bearer your_token_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john@example.com"
  }'

{
  "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@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@example.com",
        "formId": "5d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a"
      }
    ]
  }
}

In this example, continue the ComplianceReview KYC by passing 5d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a to Get Session ID. The first result is an empty KYC opened later on the current form version.

Find submissions by email

curl -X POST \
  '{base_url}/ExtForm/submissions/search' \
  -H 'Authorization: Bearer your_token_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "formId": "7ac9ab5e-4123-4456-b8c3-123456789012",
    "email": "john@example.com"
  }'

Find submissions with expiry date within the next 10 days

curl -X POST \
  '{base_url}/ExtForm/submissions/search' \
  -H 'Authorization: Bearer your_token_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "formId": "7ac9ab5e-4123-4456-b8c3-123456789012",
    "states": ["Approved"],
    "filters": [
      {
        "fieldId": "expiry-date-field-id",
        "value": "2026-02-20",
        "operator": "LessThanOrEqual"
      }
    ]
  }'

Combine multiple filters (AND logic)

curl -X POST \
  '{base_url}/ExtForm/submissions/search' \
  -H 'Authorization: Bearer your_token_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "formId": "7ac9ab5e-4123-4456-b8c3-123456789012",
    "states": ["Onboarding", "ComplianceReview"],
    "filters": [
      {
        "fieldId": "name-field-id",
        "value": "John",
        "operator": "Contains"
      },
      {
        "fieldId": "amount-field-id",
        "value": "5000",
        "operator": "GreaterThan"
      }
    ]
  }'

Error Handling

Status Code	Description	Solution
400	Invalid form ID	Check that the form ID is correctly formatted
400	formId cannot be empty; omit it to cover every KYC form	formId was sent as an empty string: pass a form ID, or leave it out (or send null)
400	formId is required when searching by field filters	Pass the formId of the form version the fields belong to
400	Invalid state value	Ensure state values exactly match the KycStateEnum names
400	Field not found	Verify the field ID exists using the Get Form Fields API
400	Unsupported field type for filtering	Only Text, TextArea, DatePicker, and Numeric fields support filtering
400	Invalid operator for field type	Check the supported operators table for the field type being filtered
400	Invalid date or numeric value	Ensure dates use yyyy-MM-dd format and numeric values are valid decimals
401	Unauthorized	Verify your authentication token
403	Forbidden	Check that your account has permission to access this form's submissions
500	Internal server error	Contact support with the error details

Important Notes

1. All filters are combined using AND logic -- a submission must match every filter to be included in the results.
2. The states parameter is optional. If omitted, submissions in all states are returned.
3. The filters parameter is optional. If omitted, the endpoint behaves like the Get Submissions API but without requiring states.
4. Field IDs can be retrieved using the Get Form Fields API.
5. The operator field defaults to Equals if not specified.

Related Resources

• Get Submissions API - Retrieve submissions filtered by state only (GET)
• Get Form Fields API - Retrieve field IDs for use in filters
• Get Forms API - Retrieve available forms
• Save Submission API - Submit form answers