Skip to main content
SmartRecruiters

Sending assessment offers programatically

 

 

Assessment providers also have the ability to create and submit offers via the dedicated API, called Offer API.

Which properties are required?

The id, catalogId, name, description, terms, and postingPeriod properties are required to perform any POST call via the Offer API. 

Please note that the same values are required when you create an offer on the UI manually. Since this is a POST call you need to provide all of these properties by default (and optionally change their values) and optionally pass additional properties so that the offer of the given id will be parsed. 

 

We do not have any endpoint over the Offer API that supports the PATCH method so that you could provide only the value(s) to update.

What we recommend here for you is first getting details of the offer to change and map its property values and then post the updates.
 

How can I update my offer? 

In general, you should call POST /offers/{offerId} assuming that the offer is not ACTIVE. 

If so, you need to POST /offers/{offerId}/withdraw it first. 

Below is an example curl request, with the minimum parameters that allow you to update an offer.

curl -X POST \

-H 'Content-Type: application/json;charset=UTF-8' \

-H 'Accept: application/json' \

-H 'X-SmartToken: {X-SmartToken}' \

-d '{

"id": "{offerId}",

"catalogId": "New Offer ID say 123 yo",

"name": "New Offer Name",

"description": "New Description",

"terms": {

"type": "REFERENCE_CHECK",

"price": {

"amount": 0,

"currencyCode": "USD"

},

"postingPeriod": 0

}

}' 'https://api.smartrecruiters.com/v1/offers/{offerId}'

Inserting and submitting offers

If I do everything via API calls, in order to create an Assessment Offer, do I need to Insert and then Submit?  If we need to update it after it's been activated, do I need to Withdraw, Update and then Submit?

A: Yes, that is correct as it reflects the UI process. First, you create an offer, then you submit it for review. If you want to update it - it needs to be withdrawn first, and submitted for review again.

Can Offers be restricted to more than one Company?

What should the syntax be if we need to restrict it to more than one client?  

Yes, they can. The companies property accepts an array of companyId strings. See the example below. 

"companies": [

   "5a7353cfe4b0aff9e7ce85e2",

   "5a55a016e4b0464c41b80902"

]

Can I create offers with the random create date and last update data values?

No. You should use SR data format or remove it from your request  body. Those values similarly like id number are added automatically by SR system.

Can the offers be preconfigured to be restricted for a specific company?

A: Yes, they can. If you want to avoid having to specify the customer's name in the offer description and/ or reaching out to your Partner Operations Consultant each time there's a new offer about to be activated, there is a way to specify the recipient on the offer creation step.

During the activation process, reach out to your Partner Operations Consultant and ask for a company ID in the context of assessment offer. You will be sent company ID parameter, which you can use in this request body:

    "companies": [
      "string"
    ],

Use the company ID you received in the place of "string", and the offer will be narrowed down to this specific company only. Doing so can make the activation and internal quality control process much faster.

Screenshot 2020-07-03 at 18.27.37.png

This feature is unavailable from the UI of your Partner Portal account.