Register a notification url

🛑

Assessment API Sunset

This API has been deprecated since September 4, 2023. The sunset date is June 10, 2024. If you are an assessment provider or looking to build an assessment integration with SmartRecruiters, please consider using the new Assessment API (2021).

SmartRecruiters can send notifications to our partners about new assessment orders as and when they are created. To receive such notifications, you can register a callback URL that will be used by the marketplace to send the ID of the new assessment order.

🚧

Usage notes

Notifications mechanism shouldn’t be the only way to find out about new orders from SmartRecruiters. This is because a notification is being sent only once. If your endpoint is not available, a notification won’t be sent again and an order will remain on the list, waiting to be handled.

In order to avoid it, you should implement a periodic check whether there are any new orders pending. To do this, please consult the List assessment orders guidelines and filter the list by orders in status NEW. This will ensure you collect and process all new orders.

Register a notification URL

You can register the callback URL by sending the Config object on the /configs endpoint. Please note that the Config object needs to have an “assessmentNotificationUrl” id.

Here is the POST request for URL registration:

curl -i
     -H "X-SmartToken:abc123"
     -H "Content-Type: application/json;charset=utf-8"
     -d @body.json
     -X POST
     https://api.smartrecruiters.com/v1/configs

body.json:

{
    "id": "assessmentNotificationUrl",
    "value": "http://api.partnercompany.com/notifications"
}

If there is a change in the URL, another POST request containing the updated value needs to be sent.

Check a notification URL

You can check how the notification URL is set up using the following GET request:

curl -i
     -H "X-SmartToken: abc123"
     -X GET
     https://api.smartrecruiters.com/v1/configs/assessmentNotificationUrl

response body:

{
    "id": "assessmentNotificationUrl",
    "value": "http://api.partnercompany.com/notifications"
}

Register a notification header

You can also configure a header that will be passed when making a call to the notification URL. You can register the header by sending the Config object on the /configs endpoint. Please note that the Config object needs to have an “assessmentNotificationHeader” id.

Here is the POST request for header registration:

curl -i
     -H "X-SmartToken:abc123"
     -H "Content-Type: application/json;charset=utf-8"
     -d @body.json
     -X POST
     https://api.smartrecruiters.com/v1/configs

body.json:

{
    "id": "assessmentNotificationHeader",
    "value": "X-Token:secret"
}

If there is a change in the header, another POST request containing the updated value needs to be sent.

Assessment Notification body

After a successful URL registration, the system will send assessment order IDs as and when each order is created. The system will send an HTTP POST request on the callback URL that you provided earlier. The body will be very simple and will contain AssessmentOrderNotification object:

{
    "assessmentOrderId": "511a3942300469a9c33819d8",
    "createDate": "2013-02-26T09:32:02.528+0000"
}