Create an Offer

🛑
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).

You will notice that creating any kind of offer using the Offer API is relatively simple and straightforward. Let’s look at the scenario of creating a sample Assessment Offer to better understand the process of creating an offer.

Create a simple Assessment Offer

Creating a new offer is as easy as sending the following POST request:

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

body.json:

{
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    }
}

The sample request above creates a very simple assessment offer that appears as “Java Developer Skill Test”. The test offered will be a ‘SKILLS_TEST’ and will be available for USD 20.

Since no availability settings are specified, the offer will be available to every industry and every location. Since this offer is also missing the targetMarket settings, it will be ranked lower than the offers that are setup specific to a target market. Please check the Offer, Availability and TargetMarket objects for more details.

Specify Offer availability

The availability object can be added to the offer to make the offer only available to specific customers. Here is a sample that uses the availability object:

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

body.json:

{
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    },
    "availability": {
        "expirationDate": "2013-02-26T09:32:02.528+0000",
        "industries": [
            {
                "id": "computer_software"
            },
            {
                "id": "internet"
            }
        ],
        "locations": [
            {
                "country": "US",
                "region": "CA",
                "city": "San Francisco"
            }
        ]
    }
}

The offer created above will only be visible to customers that have openings in the ‘computer_software’ and ‘internet’ industries. Also, it will only be visible for customers looking for employees in the city of San Francisco. For a list of available industries please check /industries.

Position Offer in the Marketplace

In order to better position an offer in the SmartRecruiters marketplace, you can make effective use of the Target Market settings: Industries, Locations, Levels and Functions.

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

body.json:

{
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    },
    "availability": {
        "expirationDate": "2013-02-26T09:32:02.528+0000",
        "industries": [
            {
                "id": "computer_software"
            },
            {
                "id": "internet"
            }
        ],
        "locations": [
            {
                "country": "US",
                "region": "CA",
                "city": "San Francisco"
            }
        ]
    },
    "targetMarket": {
        "industries": [
            {
                "id": "computer_software"
            },
            {
                "id": "internet"
            }
        ],
        "functions": [
            {
                "id": "engineering"
            }, 
            {
                "id": "research"
            }
        ],
        "experienceLevels": [
            {                
                "id": "mid_senior_level"
            }
        ],
        "locations": [
            {
                "country": "US",
                "region": "California",
                "city": "San Francisco"
            }
        ]
    }
}

Hence, adding the targetMarket object allows you to position your offer in SmartRecruiters marketplace specific to your target customers. Offer with specific targetMarket settings will be ranked higher for requests matching given locations, functions, experience levels and industries. For a list of available functions, industries and experience levels please check appropriate endpoint descriptions: /functions, /industries, /levels.

Setting offer category

While creating the offers, you can group them into categories. Offers from the same category, can be later on bundled and sold together. To assign a category to offer simply add a “category” field into it. Category value can be any string you choose. Offer below will be of a STANDARD category. Later on MarketPlace UI you can create a new bundle offer (e.g. an offer for 100 STANDARD tests)

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

body.json:

{
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "category": "STANDARD",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    },
    "availability": {
        "specialOffer" : "25% OFF"
    }
}

Creating special offers

An offer can be marked as ‘Special’. Such an offer helps promoting a value offer that you may list to stand apart from the other offers in the marketplace. To create a special offer, specify the ‘specialOffer’ string inside the Availability object. Here is the sample to create a special offer.

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

body.json:

{
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    },
    "availability": {
        "specialOffer" : "25% OFF"
    }
}

The above sample will create an offer that will be featured in a separate section in the marketplace reserved for special offers. The “25% OFF” label will be added to the offer description.

Setting offer expiration date

You can set up timed based offer using expiration date. An offer expiration date can be specified on availability object. If expiration date is set, an offer will become inactive (and it will disappear from the store) after passing the specified date. Request below set’s up time based offer:

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

body.json:

{
    "catalogId": "ab-32-gf-asd",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    },
    "availability": {
        "expirationDate": "2013-02-26T12:50:02.594+0000"
    }
}

Offer creation response

Each offer creation request described above will return a response body with an Offer object. After a successful offer creation, a unique id will be assigned to the offer. This id will then be used to retrieve particular offers. An example response might look similar to this:

{
    "id" : "511a3942300469a9c33819d8",
    "createDate": "2013-03-13T12:05:46.398+0000",
    "lastUpdateDate": "2013-03-13T12:05:46.398+0000",
    "catalogId": "ab-32-gf-asd",
    "status" : "INACTIVE",
    "name": "Java Developer Skill Test",
    "description": "Senior Java Developer Test",
    "terms": {
        "type": "SKILLS_TEST",
        "price": {
            "amount": "20.00",
            "currencyCode": "USD"
        }
    },
    "availability": {
        "specialOffer" : "25% OFF"
    }
}

🛑Assessment API Sunset

Create a simple Assessment Offer

Specify Offer availability

Position Offer in the Marketplace

Setting offer category

Creating special offers

Setting offer expiration date

Offer creation response

🛑
Assessment API Sunset