Applicant Invitation

The Applicant Invitation endpoint is designed to dispatch invitations to candidates for a specific job position. By providing the unique identifier for the position and a list of candidate email addresses, the system will automatically send invitation emails to the specified recipients. These emails enable candidates to initiate their examination process.

---

Endpoint Overview

• HTTP Method: POST
• Endpoint URL:
  https://api.vinter.me/api/v1/Invitation/SendInvitation

---

Request Headers

Header Name	Description	Example Value
X-Api-Key	API key used for organizational authentication.	api_key
Content-Type	Specifies the media type of the request body.	application/json

---

Request Body

The request body must be a valid JSON object containing the following properties:

Parameter Name	Type	Required	Description
positionId	String	Yes	The unique identifier of the position for which invitations are sent.
applicantEmails	Array	Yes	A list of email addresses for the candidates to be invited.

Example Request Body

{
  "positionId": "2ec6acd7-b976-4a58-aff4-e32c4121d73f",
  "applicantEmails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

Response Format

Upon successful processing of the request, the API will return a JSON response in the following structure:

{
  "data": [
    {
      "applicantEmail": "[email protected]",
      "invitationID": "e9e4154c-8ba6-4199-b25b-b734dd74ef1d",
      "isSuccess": "false",
      "errorMessage": "Existing HR User" // Indicates the candidate is already associated as an HR user
    },
    {
      "applicantEmail": "[email protected]",
      "invitationID": "6efe44b3-c4fa-477d-a38b-ca280b2cca13",
      "isSuccess": "true",
      "errorMessage": "Existing Invitation" // Indicates the candidate is already listed as an applicant. No Invitation is sent again.
    },
    {
      "applicantEmail": "[email protected]",
      "invitationID": "5ecfef9e-ba28-4c3d-a00c-06780aefda3c",
      "isSuccess": "true",
      "errorMessage": null // The invitation was successfully processed without any issues
    }
  ],
  "success": true,
  "message": null,
  "isResourceKey": true
}

Field Descriptions

• isSuccess:
  Indicates whether the invitation was successfully sent. If false, the associated errorMessage explains why it failed.

• errorMessage:
  Provides context about why an invitation failed. For example, "Existing HR User" indicates that the candidate is already registered as an HR user, preventing the invitation from being sent.

• invitationID:
  A unique identifier for each invitation sent. Useful for tracking and troubleshooting.

• data:
  A list of invitation results. Each entry includes the applicant’s email, whether the invitation was successful, and any relevant error messages.

• success:
  A boolean indicating if the overall operation was successfully processed.

---

Use Cases

• First-Time Invitations: Send initial invitations to new candidates who have not yet received an invitation.
• Systematic Onboarding: Quickly onboard multiple candidates by providing a standardized invitation process.
• Operational Transparency: Ensure that all invitation attempts are logged and associated with detailed outcomes, making auditing and troubleshooting simpler.

---

Error Codes

HTTP Code	Status	Description
400	Bad Request	The request contains invalid or improperly formatted parameters.
401	Unauthorized	Authentication failed due to a missing or invalid API token.
404	Not Found	The requested resource (e.g., the position) could not be found.
500	Internal Error	An internal server error occurred during the request processing.