Get Forms

The Get Forms API allows you to retrieve a list of available forms in the system filtered by form type. This is typically used as a first step in the form submission workflow to identify which form templates are available for a customer to complete.

API Endpoint

GET {base_url}/ExtForm/forms

Request Format

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

Query Parameters

Parameter	Type	Required	Default	Description
includeVersions	boolean	No	false	Also return every version of each form. See Form versions

Request Headers

Authorization: Bearer {token}

Response Format

{
  "statusCode": 200,
  "messages": ["Processed successfully"],
  "result": {
    "count": 2,
    "forms": [
      {
        "formId": "7ac9ab5e-4123-4456-b8c3-123456789012",
        "formName": "Individual KYC Form"
      },
      {
        "formId": "8bd0bc6f-5234-5567-c9d4-234567890123",
        "formName": "Corporate KYC Form"
      }
    ]
  }
}

Response Fields

Field	Description
count	Total number of forms returned
forms	Array of form objects
forms[].formId	Unique identifier for the form
forms[].formName	Display name of the form
forms[].versions	Every version of the form, newest first. Only returned with includeVersions=true

Form versions

Editing a form creates a new version with a new formId. This endpoint always returns the current version, but customers who onboarded earlier stay on the version they started.

Get Session ID opens the customer's KYC for the formId you pass: an existing customer who has no submission on that form gets a new, empty one. To continue a customer's existing KYC, pass the formId of the version it was started on. To start a new KYC on the latest version, pass the current formId.

Older versions stay active: their formId keeps working in Get Session ID. If you keep passing an older formId, new customers will onboard on that older version until you switch to the current one.

Use includeVersions=true to list the versions:

curl -X GET \
  '{base_url}/ExtForm/forms?includeVersions=true' \
  -H 'Authorization: Bearer your_token_here'

{
  "statusCode": 200,
  "messages": ["Processed successfully"],
  "result": {
    "count": 1,
    "forms": [
      {
        "formId": "7ac9ab5e-4123-4456-b8c3-123456789012",
        "formName": "Individual KYC Form",
        "versions": [
          {
            "formId": "7ac9ab5e-4123-4456-b8c3-123456789012",
            "createdAt": "2026-03-01T09:00:00Z",
            "supersededAt": null,
            "submissionsCount": 12
          },
          {
            "formId": "5d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
            "createdAt": "2026-01-15T09:00:00Z",
            "supersededAt": "2026-03-01T09:00:00Z",
            "submissionsCount": 30
          }
        ]
      }
    ]
  }
}

Field	Description
versions[].formId	Id of this version — accepted by Get Session ID and the submission APIs
versions[].createdAt	When this version was created (UTC). null for some older forms with no recorded creation date; those are listed last
versions[].supersededAt	When a newer version replaced it (UTC). null on the current version
versions[].submissionsCount	Active submissions on this version that your credentials can access

To find the version a specific customer is on, use Search Submissions with the customer's email and no formId: each result includes the formId of the version it was started on. If the customer has more than one KYC, choose by kycState, not by position (results are newest first).

Example Usage

cURL Example

curl -X GET \
  '{base_url}/ExtForm/forms' \
  -H 'Authorization: Bearer your_token_here'

Error Handling

Status Code	Description	Solution
400	Invalid request parameters
401	Unauthorized	Verify your authentication token
403	Forbidden	Check that your account has permission to access forms
500	Internal server error	Contact support with the error details

Related Resources

• Get Form Fields API - Retrieving detailed form structure and fields
• Save Submission API - Submitting form answers