Forms

Forms are the backbone of the application process in Semantikmatch. They help collect candidate information, including answers to questions and document uploads. On this page, we'll dive into the different form endpoints you can use to manage forms programmatically. We'll look at how to query, create, update, and delete forms.

Like every model in Semantikmatch, the form can be set up directly through the Semantikmatch backoffice. Once configured, forms can be used to manage applications.

The Form Model

The form model contains all the information about a form, including the title, steps, and fields. Forms are used to guide applicants through various stages of an application process.

Example Form Format

{
  "id": "09bd225c-651a-404e-876a-7458b3cb03b3",
  "title": "BBA Program",
  "created_at": "2025-05-05T14:39:26.863Z",
  "modified_at": "2025-05-05T14:39:26.863Z",
  "steps": [
    {
      "name": "Eligibility",
      "description": null,
      "fields": [
        {
          "name": "ID",
          "type": null
        },
        {
          "name": "diploma",
          "type": null
        },
        {
          "name": "school certificate",
          "type": null
        },
        {
          "name": "academic transcript",
          "type": null
        },
        {
          "name": "english test",
          "type": null
        }
      ]
    }
  ]
}

Properties

Name
id
Type
string
Description
Unique identifier for the form.
Name
title
Type
string
Description
The title of the form.
Name
created_at
Type
string
Description
ISO timestamp of when the form was created.
Name
modified_at
Type
string
Description
ISO timestamp of when the form was last modified.
Name
steps
Type
array
Description
An array of steps, each containing fields.
Each step is an object with the following properties:
- name: string
- description: string or null
- fields: Array of fields
Name
fields
Type
array
Description
A field is an object to define the data that will be collected from the applicant.
Each field within a form has the following properties:
- name: string
- type: string or null

Field Type

Each field within a form have a specific type, which determines the kind of data it can hold. The available field types are:

info: Provides informational content.
question: Represents a question that requires an answer.
attachment: Allows for file uploads.
video: Requires a video response.
url: Accepts a URL input.

GET/api/forms

List All Forms

This endpoint allows you to retrieve a paginated list of all your forms. By default, a maximum of ten forms are shown per page.

Optional Parameters

Name
page
Type
integer
Description
The page number to retrieve.
Name
limit
Type
integer
Description
Limit the number of forms returned.
Name
id
Type
string
Description
Filter by form ID.
Name
name
Type
string
Description
Filter by form name.
Name
created_at
Type
string
Description
Filter by creation date.

List Forms

curl "https://api.semantikmatch.com/api/forms?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "forms": [
    {
      "id": "09bd225c-651a-404e-876a-7458b3cb03b3",
      "title": "BBA Program",
      "created_at": "2025-05-05T14:39:26.863Z",
      "modified_at": "2025-05-05T14:39:26.863Z",
      "steps": [
        {
          "name": "Eligibility",
          "description": null,
          "fields": [
            {
              "name": "ID",
              "type": null
            },
            {
              "name": "diploma",
              "type": null
            }
          ]
        }
      ]
    },
    {
      "id": "50b23f9a-1670-48f8-a666-e64011cb43e2",
      "title": "MBA Program",
      "created_at": "2025-05-04T10:15:42.301Z",
      "modified_at": "2025-05-04T10:15:42.301Z",
      "steps": [
        {
          "name": "Apply Phase",
          "description": null,
          "fields": [
            {
              "name": "CV",
              "type": "attachment"
            },
            {
              "name": "ID",
              "type": "attachment"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 10
  }
}

POST/api/forms

Create a Form

This endpoint allows you to create a new form in Semantikmatch. You can define the title, steps, and fields of the form.

Required Parameters

Name
name
Type
string
Description
The title of the form.
Name
steps
Type
array
Description
An array of steps, each containing fields.

Create a Form

curl https://api.semantikmatch.com/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MBA Program",
    "steps": [
      {
        "name": "Apply Phase",
        "fields": [
          {
            "name": "CV",
            "type": "attachment"
          },

          {
            "name": "Transcript",
            "type": "attachment"
          },

          {
            "name": "ID",
            "type": "attachment"
          },

          {
            "name": "GMAT_OR_MANAGEMENT",
            "type": "attachment"
          },

          {
            "name": "TOEFL_OR_ENGLISH",
            "type": "attachment"
          }
        ]
      }
    ]
  }'

Response

{
  "id": "50b23f9a-1670-48f8-a666-e64011cb43e2",
  "title": "MBA Program",
  "created_at": "2025-05-05T12:00:00Z",
  "modified_at": "2025-05-05T12:00:00Z",
  "steps": [
    {
      "name": "Apply Phase",
      "description": null,
      "fields": [
        {
          "name": "CV",
          "type": "attachment"
        },
        {
          "name": "Transcript",
          "type": "attachment"
        },
        {
          "name": "ID",
          "type": "attachment"
        },
        {
          "name": "GMAT_OR_MANAGEMENT",
          "type": "attachment"
        },
        {
          "name": "TOEFL_OR_ENGLISH",
          "type": "attachment"
        }
      ]
    }
  ]
}

GET/api/forms/:id

Retrieve a Form

This endpoint allows you to retrieve a specific form by providing its ID. The response includes all steps and fields associated with the form.

Get Form Details

curl "https://api.semantikmatch.com/api/forms/09bd225c-651a-404e-876a-7458b3cb03b3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "09bd225c-651a-404e-876a-7458b3cb03b3",
  "title": "BBA Program",
  "created_at": "2025-05-05T14:39:26.863Z",
  "modified_at": "2025-05-05T14:39:26.863Z",
  "steps": [
    {
      "name": "Eligibility",
      "description": null,
      "fields": [
        {
          "name": "ID",
          "type": null
        },
        {
          "name": "diploma",
          "type": null
        },
        {
          "name": "school certificate",
          "type": null
        },
        {
          "name": "academic transcript",
          "type": null
        },
        {
          "name": "english test",
          "type": null
        },
        {
          "name": "management test",
          "type": null
        },
        {
          "name": "French test",
          "type": null
        },
        {
          "name": "essay",
          "type": null
        },
        {
          "name": "resume",
          "type": null
        }
      ]
    }
  ]
}

PUT/api/forms/:id

Update a Form

This endpoint allows you to completely update a form by its ID. You must provide the entire form structure, as this will replace the existing form.

Required Parameters

Name
title
Type
string
Description
The title of the form.
Name
steps
Type
array
Description
An array of steps, each containing fields.

Update a Form

curl -X PUT "https://api.semantikmatch.com/api/forms/09bd225c-651a-404e-876a-7458b3cb03b3" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated BBA Program",
  "steps": [
    {
      "name": "Eligibility",
      "description": "Required documents for eligibility assessment",
      "fields": [
        {
          "name": "ID",
          "type": "attachment"
        },
        {
          "name": "diploma",
          "type": "attachment"
        },
        {
          "name": "school certificate",
          "type": "attachment"
        },
        {
          "name": "academic transcript",
          "type": "attachment"
        },
        {
          "name": "english test",
          "type": "attachment"
        }
      ]
    },
    {
      "name": "Additional Documents",
      "description": "Additional information for your application",
      "fields": [
        {
          "name": "motivation letter",
          "type": "attachment"
        },
        {
          "name": "recommendation letters",
          "type": "attachment"
        }
      ]
    }
  ]
}'

Response

{
  "id": "09bd225c-651a-404e-876a-7458b3cb03b3",
  "title": "Updated BBA Program",
  "created_at": "2025-05-05T14:39:26.863Z",
  "modified_at": "2025-05-05T16:21:08.472Z",
  "steps": [
    {
      "name": "Eligibility",
      "description": "Required documents for eligibility assessment",
      "fields": [
        {
          "name": "ID",
          "type": "attachment"
        },
        {
          "name": "diploma",
          "type": "attachment"
        },
        {
          "name": "school certificate",
          "type": "attachment"
        },
        {
          "name": "academic transcript",
          "type": "attachment"
        },
        {
          "name": "english test",
          "type": "attachment"
        }
      ]
    },
    {
      "name": "Additional Documents",
      "description": "Additional information for your application",
      "fields": [
        {
          "name": "motivation letter",
          "type": "attachment"
        },
        {
          "name": "recommendation letters",
          "type": "attachment"
        }
      ]
    }
  ]
}

DELETE/api/forms/:id

Delete a Form

This endpoint allows you to delete a specific form by its ID. Once deleted, all steps and fields associated with the form will be removed.

Delete a Form

curl -X DELETE "https://api.semantikmatch.com/api/forms/09bd225c-651a-404e-876a-7458b3cb03b3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "message": "Form deleted successfully",
  "form": {
    "id": "09bd225c-651a-404e-876a-7458b3cb03b3",
    "title": "BBA Program",
    "created_at": "2025-05-05T14:39:26.863Z",
    "modified_at": "2025-05-05T14:39:26.863Z"
  }
}