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, 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, sections, steps, and fields. Forms are used to guide applicants through various stages of an application process (e.g., "Inscription", "Admission").

Example Form Format

{
  "title": "Sample Form",
  "sections": [
    {
      "name": "Eligibility",
      "steps": [
        {
          "name": "Administrative",
          "fields": [
            {
              "name": "ID",
              "type": "attachment"
            }
          ]
        },
        {
          "name": "Academic",
          "fields": [
            {
              "name": "GMAT",
              "type": "attachment"
            },
            {
              "name": "TOEIC",
              "type": "attachment"
            },
            {
              "name": "Last Diploma",
              "type": "attachment"
            }
          ]
        }
      ]
    },
    {
      "name": "Admission",
      "steps": [
        {
          "name": "Profil",
          "fields": [
            {
              "name": "Explain your motivation",
              "type": "video"
            },
            {
              "name": "Github",
              "type": "url"
            }
          ]
        }
      ]
    }
  ]
}

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
timestamp
Description
Timestamp of when the form was created.
Name
sections
Type
array
Description
An array of sections, each containing steps and fields.
Each section is an object with the following properties:
- name: string
- steps: Array of steps
Name
steps
Type
array
Description
A step is an object to define the data that will be collected from the applicant.
Each step is an object with the following properties:
- name: string
- 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 have a specific type, which determines the kind of data it can hold.

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/v1/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.
Name
status
Type
string
Description
Filter by form status.

Request

GET

/v1/forms

curl -G https://api.semantikmatch.com/v1/forms \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=10

Response

{
  "forms": [
    {
      "id": "50b23f9a-1670-48f8-a666-e64011cb43e2",
      "title": "Executive MBA",
      "created_at": "2024-10-30T22:38:29.211Z",
      "modified_at": "2024-10-30T22:38:29.211Z",
      "sections": [...]
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}

POST/v1/forms

Create a Form

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

Required Parameters

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

Request

POST

/v1/forms

curl https://api.semantikmatch.com/v1/forms \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "High School Admission Form",
    "sections": [
      {
        "name": "Inscription",
        "steps": [
          {
            "name": "Personal Information",
            "fields": [
              {
                "name": "full name",
                "type": "info"
              },
              {
                "name": "Describe your motivation in a short video.",
                "type": "video"
              },
              {
                "name": "Upload your CV.",
                "type": "attachment"
              }
            ]
          }
        ]
      }
    ]
  }'

Response

{
  "id": "1",
  "title": "High School Admission Form",
  "sections": [...],
  "created_at": "2024-10-30T22:38:29.211Z",
  "modified_at": "2024-10-30T22:38:29.211Z"
}

GET/v1/forms/:id

Retrieve a Form

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

Request

GET

/v1/forms/{id}

curl https://api.semantikmatch.com/v1/forms/1 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "1",
  "title": "High School Admission Form",
  "sections": [...],
  "created_at": "2024-10-30T22:38:29.211Z",
  "modified_at": "2024-10-30T22:38:29.211Z"
}

DELETE/v1/forms/:id

Delete a Form

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

Request

DELETE

/v1/forms/{id}

curl -X DELETE https://api.semantikmatch.com/v1/forms/1 \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Form deleted successfully",
  "form": {
    "id": "1",
    "title": "High School Admission Form",
    "created_at": "2024-10-30T22:38:29.211Z",
    "modified_at": "2024-10-30T22:38:29.211Z",
    "sections": [...]
  }
}