SmartRecruiters offers collections of APIs to enable developers to access SmartRecruiters resources to build custom hiring solutions on top of the SmartRecruiters platform. This guide walks you through the key setup process of obtaining credentials and testing SmartRecruiters APIs.

Step 1: Identify the target audience of your solution

Whether you are a SmartRecruiters customer or partner, you can build with SmartRecruiters APIs. However, it's important to identify the audience of your solution so you can obtain credentials from the right channel.

Consider the following questions:

Are you a SmartRecruiters customer? Or are you a SmartRecruiters partner?
Are you building a custom solution only for your organization or a specific customer? Or are you planning to distribute your solution on SmartRecruiters Marketplace to all SmartRecruiters customers?

Step 2: Obtain a credential

SmartRecruiters Customer

If you are a SmartRecruiters customer and would like to build a custom solution for your organization, you can obtain API credentials from your SmartRecruiters Credential Manager.

SmartRecruiters offers both API keys and OAuth. When generating a new credential, you can choose between two options:

API Keys: An API key provides its user access to all SmartRecruiters API. Use an API key if you are testing out SmartRecruiters API.
OAuth Client Credential: A client credential provides its user access to SmartRecruiters API limited by its access scope. Use client credentials for your live applications as OAuth generally provides better security and control.

SmartRecruiters Partner

As a SmartRecruiters partner, there are two ways to obtain an API credential:

Suppose you are looking to build a custom solution for a specific SmartRecruiter customer. In that case, you should contact the customer's admins to obtain an API credential from the customer's SmartRecruiters Credential Manager.
If you are a SmartRecruiters partner looking to distribute your solution for all SmartRecruiters customers via our Marketplace, contact our Partner Success Team) to obtain an API credential.

Step 3: Make an API request

After you've obtained an API credential, you are now ready to make a call to the SmartRecruiters API.

There are various interactive tools (e.g. Postman) and methods available in the market that you can use to make a SmartRecruiters API request. Alternatively, you can try any API endpoint directly from the corresponding page of this documentation.

Make a test API call

Depending on the access scope of your credential, the endpoint and resource your access may be limited.

For illustration, let us make a test API to add a new user to your SmartRecruiter account using the create.user endpoint. To add a new user, the following information is required:

First Name: This is the first name of the user which will be displayed under the user profile and his/her communication with candidates, interview scheduling, and other users in SmartRecruiters.
Last Name: This is the last name of the user which will be displayed under the user profile and his/her communication with candidates, interview scheduling, and other users in SmartRecruiters
System Role: SmartRecruiters system role plays a part in user access to jobs, candidate profiles, and some SmartRecruiters features.
- System Role ID: The string identifier of the system role. You can create a custom system role for your organization. Still, for this test call, we'll use the value 'ADMINISTRATOR' which is one of the 5 standard system roles pre-defined for every SmartRecruiters company.
Language Code: SmartRecruiters supports various languages to display. The value in Language Code determines the user interface language displayed in SmartRecruiters.For this test call, let us use the value 'en' for English.
Location: Location represents the physical location of the user. Location is an array and two attributes in the array are required:
- Country Code: ISO Alpha 2 country code of the user's location. For this test call, let us use the value 'US' for the United States
- City: City of the user's location. For this test call, let us use the value 'San Francisco'
Authorization Information: Depending on your credential type, you should include authorization information in the header of your call.
- If you are using an API key, include theX-SmartToken and the respective API key value in the header.
- If you are using an OAuth credential, exchange your OAuth credential for an access token via the token endpoint and include Authorization and respective token value in the header.

To make a test call, you can copy and paste the command line below and replace the value in X-SmartToken with your own API key or replace it with Authorization: Bearer 'your-access-token-value' if you are using OAuth credentials.

curl -X POST "https://api.smartrecruiters.com/jobs" \
-H "Content-Type: application/json" \
-H "X-SmartToken: DCRA1-d0b1128084fb427ea**************" \
-d '{
	"firstname": "Susan",
	"lastname": "Santos", 
	"systemRole": {"id": "ADMINISTRATOR"}, 
	"language": {"code":"en"},
	"location": {"countryCode": "US", "city":"San Francisco"}
 }'

curl -X POST "https://api.smartrecruiters.com/jobs" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer DCRA1-d5c77a928320f57ef60329e7****************" \
-d '{
	"firstname": "Susan",
	"lastname": "Santos", 
	"systemRole": {"id": "ADMINISTRATOR"}, 
	"language": {"code":"en"},
	"location": {"countryCode": "US", "city":"San Francisco"}
 }'

If the call is successful, you should receive a201 Created Job code and the following JSON response:

{
  "firstName": "Susan",
  "lastName": "Santos",
  "systemRole": {
    "id": "ADMINISTRATOR",
    "name": "ADMINISTRATOR"
  },
  "language": {
    "code": "en"
  },
  "active": true,
  "updatedOn": "2021-05-28T19:03:11.567Z",
  "location": {
    "country": "United States",
    "countryCode": "US",
    "city": "San Francisco"
  }
}

If you are using SmartRecruiters API Explorer, follow the steps below:

Navigate to SmartRecruiters API Reference. Under the 'Job' resources, find the create.job endpoint.
Provide the value for Job Title, Location, Industry, Function, and Experience Level
Provide your API key or access token you've obtained from exchanging your OAuth credential via the token endpoint.
Click 'Try It' to send an API request to create a job
Review the following:
a. You have received a 201 Created Job response from the call
b. Log into your SmartRecruiters account, check the job has been created under the 'Jobs' tab.