Applicant Force Invitation

The Applicant Force Invitation endpoint is specifically designed to resend invitations to candidates for a specific job position. Unlike the standard invitation process, this endpoint targets recipients who have already been invited in the past, ensuring that those candidates receive a renewed invitation email, even if they previously did not respond or engage. This process allows organizations to maintain clear communication and streamline their hiring workflows.

---

Endpoint Overview

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

---

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"
    },
    {
      "applicantEmail": "[email protected]",
      "invitationID": "6efe44b3-c4fa-477d-a38b-ca280b2cca13",
      "isSuccess": "true",
      "errorMessage": null
    },
    {
      "applicantEmail": "[email protected]",
      "invitationID": "5ecfef9e-ba28-4c3d-a00c-06780aefda3c",
      "isSuccess": "true",
      "errorMessage": null
    }
  ],
  "success": true,
  "message": null,
  "isResourceKey": true
}

---

Detailed Field Descriptions

• isSuccess:
  This field indicates whether the re-invitation for a specific candidate was successfully sent. A value of true signifies that the email was successfully re-sent, while false indicates that the operation encountered an error.

• errorMessage:
  If isSuccess is false, this field will contain an explanatory message describing why the re-invitation failed. For example, "Existing HR User" might mean the recipient is already listed in the system as an HR representative, preventing the re-invitation.

• invitationID:
  A unique identifier associated with the invitation attempt. This helps track individual invitation attempts for auditing or troubleshooting.

• data:
  Contains a list of results, one per recipient email. Each entry in the list includes the recipient’s email address, the unique invitationID, and the success status and error message for that specific invitation.

• success:
  Indicates whether the overall operation was processed successfully. While individual invitations may fail, this field refers to the success of processing the request itself.

---

Use Cases

• Re-engagement: Re-invite candidates who didn’t respond to previous invitations, helping keep the talent pipeline active.
• Error Resolution: Correct issues for candidates who previously had incorrect email addresses or other blocking errors, ensuring they receive the necessary invitation.
• Streamlined Communication: Maintain a consistent communication channel with candidates, ensuring they have the most up-to-date information about their application status.

---

Error Codes

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