Applications

Applications are the submissions candidates make in response to your forms. Each application includes the candidate's answers to form fields, such as attachments, responses, and other submitted data. On this page, we'll dive into the different application endpoints you can use to manage applications programmatically. We'll look at how to query, create, update, and delete applications.

The application model

The application model contains all the data submitted by a candidate in response to a form, such as their answers to questions, uploaded documents, and status.

Properties

Name
id
Type
string
Description
Unique identifier for the application.
Name
form_id
Type
string
Description
The form to which the application belongs.
Name
candidate_data
Type
object
Description
The data submitted by the candidate, including their responses and uploaded documents.
Name
status
Type
string
Description
The current status of the application. Possible values are: "pending", "processing", "finished", "error".
Name
created_at
Type
timestamp
Description
Timestamp of when the application was submitted.

GET/api/applications

List all applications

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

Optional query parameters

Name
jobId
Type
string
Description
The ID of the job for which applications are being retrieved.
Name
candidateId
Type
string
Description
The ID of the candidate whose applications are being retrieved.
Name
limit
Type
integer
Description
Limit the number of applications returned (default is 10).
Name
offset
Type
integer
Description
The offset for pagination (default is 0).
Name
status
Type
string
Description
Filter applications by their status. Possible values are: "pending", "processing", "finished", "error".
Name
agg_created_at
Type
string
Description
Filter applications by creation date.
Name
agg_modified_at
Type
string
Description
Filter applications by modification date.

List Applications

Retrieve a paginated list of all submitted applications with optional filtering.

curl -G https://gateway.semantikmatch.com/api/applications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d limit=10\
  -d status=finished

Response

{
  "has_more": false,
  "data": [
    {
      "agg_id": "9c9d7ce8-d565-4e53-b0a2-cf969ba282c8",
      "agg_created_at": "2024-11-27T15:30:04.396Z",
      "agg_modified_at": "2024-11-27T15:34:09.746Z",
      "agg_candidate_id": "fc4dfa93-aa6c-41a3-a340-5c222958370d",
      "agg_job_id": "50b23f9a-1670-48f8-a666-e64011cb43e2",
      "status": "finished",
      "candidate": {
        "agg_id": "fc4dfa93-aa6c-41a3-a340-5c222958370d",
        "agg_firstname": "John",
        "agg_lastname": "Doe",
        "email": "john.doe@example.com"
      }
    }
  ]
}

POST/api/applications/submit

Submit a Candidate Application

This endpoint allows you to submit a new application along with files for a specific job. Applications contain the candidate's data, such as answers to questions and document uploads.

Required attributes

Name
firstname
Type
string
Description
The first name of the candidate.
Name
lastname
Type
string
Description
The last name of the candidate.
Name
email
Type
string
Description
The email address of the candidate.
Name
jobId
Type
string
Description
The ID of the job for which the application is being submitted.
Name
files
Type
array
Description
An array of files to be uploaded with the application.

Submit a Candidate

curl -X POST https://api.semantikmatch.com/v1/applications/submit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "firstname=John" \
  -F "lastname=Doe" \
  -F "email=john.doe@example.com" \
  -F "jobId=YOUR_JOB_ID" \
  -F "CV=@/path/to/cv.pdf" \
  -F "Transcript=@/path/to/transcript.pdf" \
  -F "ID=@/path/to/id.pdf" \
  -F "GMAT_OR_MANAGEMENT=@/path/to/gmat-or-management.pdf" \
  -F "TOEFL_OR_ENGLISH=@/path/to/toefl-or-english.pdf" \ \
  -F "client_data={\"candidate_id\":\"CRM-12345\",\"source\":\"internal_system\"}"

Response

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "john.doe@example.com",
  "applicationId": "501" // The ID of the created application
}

POST/api/applications/{id}/attachments

Update Application with Attachments

This endpoint allows you to update an existing application with additional files or attachments. When you add new attachments to an application, it will automatically trigger a re-evaluation of the application if it was previously completed.

Path parameters

Name
id
Type
string
Description
The ID of the application to update.

Multipart form data

Name
files
Type
array
Description
Files to be uploaded. The field name will be preserved as the document type identifier.

Notes

When an application is updated with new attachments:

If the application was previously completed (status "ended" or "finished"), it will be reset to "pending" status
Existing evaluation results will be cleared to allow for fresh evaluation with the new attachments
The field names you use for the files in the multipart form will be preserved as document type identifiers

Update Application Attachments

curl -X POST https://api.semantikmatch.com/api/applications/YOUR_APPLICATION_ID/attachments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "Additional_Document=@/path/to/additional_document.pdf" \
  -F "Updated_Resume=@/path/to/updated_resume.pdf" \
  -F "Reference_Letter=@/path/to/reference_letter.pdf"

Response

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "john.doe@example.com",
  "applicationId": "YOUR_APPLICATION_ID"
}

GET/api/applications/{id}

Retrieve an application

This endpoint allows you to retrieve a specific application by providing its ID. The response includes all the data submitted by the candidate, including candidate information, client data, and all associated attachments.

Path parameters

Name
id
Type
string
Description
The ID of the application to retrieve.

Response

The response includes an attachments array with details about all files submitted with the application:

Name
attachments
Type
array
Description
Array of attachment objects with the following properties:
- id: Unique identifier for the attachment
- type: Type of attachment (e.g., "attachment", "video")
- field_name: Field name associated with this attachment
- status: Current status of the attachment processing
- created_at: Timestamp when the attachment was created

Get Application by ID

curl https://api.semantikmatch.com/api/applications/501 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "501",
  "agg_job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "status": "finished",
  "agg_created_at": "2025-01-01T12:00:00Z",
  "agg_modified_at": "2025-01-02T15:30:45Z",
  "client_data": {
    "source": "API submission",
    "referrer": "Website"
  },
  "candidate": {
    "id": "9a27d6b5-e6c1-4af2-9d76-1ab85cb82f22",
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com"
  },
  "attachments": [
    {
      "id": "12345",
      "type": "attachment",
      "field_name": "CV",
      "status": "finished",
      "created_at": "2025-01-01T12:05:23Z"
    },
    {
      "id": "12346",
      "type": "attachment",
      "field_name": "Transcript",
      "status": "finished",
      "created_at": "2025-01-01T12:06:45Z"
    },
    {
      "id": "12347",
      "type": "video",
      "field_name": "Presentation",
      "status": "processing",
      "created_at": "2025-01-01T12:08:12Z"
    }
  ]
}

DELETE/api/applications/{id}

Delete an application

This endpoint allows you to delete a specific application by its ID. Once deleted, all the submitted data, including attachments and evaluation results, will be permanently removed.

Path parameters

Name
id
Type
string
Description
The ID of the application to delete.

Delete Application

curl -X DELETE https://api.semantikmatch.com/api/applications/YOUR_APPLICATION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "message": "Application deleted successfully"
}

Using Client Data

The client_data field allows you to include custom data when submitting applications. This data will be returned in webhook responses, making it easier to associate SemantikMatch evaluations with records in your system.

Common uses for client_data include:

Including your internal candidate ID
Tracking application source or campaign
Adding metadata about the application process
Including any reference numbers for your CRM

The client_data field accepts a JSON string that will be parsed when returned in webhook responses.