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 the form ID, optional state filters, and optional field-level filters.

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	Yes	The unique identifier of the form to search submissions for
`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). 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"`
RichTextBox	`Equals`, `Contains`	Plain string	`"content to search"`
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"`

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

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

Example Usage

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	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, RichTextBox, 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

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

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

API Endpoint​

Request Format​

Request Headers​

Request Body​

Request Body Fields​

Filter Object​

Filter Operators​

Supported Field Types for Filtering​

Valid KYC State Values​

Response Format​

Response Fields​

Example Usage​

Find submissions by email​

Find submissions with expiry date within the next 10 days​

Combine multiple filters (AND logic)​

Error Handling​

Important Notes​

Related Resources​