Get Started

Build With SmartRecruiters

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

Step 1: Identify the target audience of your solution

Whether you are a SmartRecruiters customer or partners, 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 distribution 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 as When generating a new credential, you can choose between two options:

  1. API Keys: An API key provides its user the access to all SmartRecruiters API. Use an API key if you are testing out SmartRecruiters API.
  2. OAuth Client Credential: A client credential provides its user access to SmartRecruiters API limited by its access scope. Use client credential 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:

  1. If you are looking to build a custom solution for a specific SmartRecruiter customer, you should get in touch with the customer's admins to obtain an API credential from the customer's SmartRecruiters Credential Manager.
  2. If you are a SmartRecruiters partner looking to distribute your solution for all SmartRecruiters customers via our Marketplace, contact our Partner Success Team @ [email protected] 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, but if you are not familiar with any, you can use the SmartRecruiters API Explorer that is available.

Make a test API call

Depending on the access scope of your credential, the endpoint and resource you can access maybe limited.

For illustration, let us make a test API to add a new user into 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 candidate, 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 candidate, interview scheduling and other users in SmartRecruiters
  • System Role: SmartRecruiters system role plays apart in user access on jobs, candidate profile and some SmartRecruiters feature.
    • System Role ID: The string identifier of the system role. You can create custom system role for your organization, but for this test call, we'll use the value 'ADMINISTRATOR' which is one of the 5 standard system role pre-defined for every SmartRecruiters company.
  • Language Code: SmartRecruiters supports various language 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 United State
    • 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 X-SmartToken and 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 201 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:

  1. Navigate to SmartRecruiters API Reference. Under the 'Job' resources, find the create.job endpoint.
  2. Provide the value for Job Title, Location, Industry, Function and Experience Level
  3. Provide your your API key or access token you've obtain from exchanging your OAuth credential via the token endpoint.
  4. Click 'Try It' to send an API request to create a job
  5. 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.

Did this page help you?