# About the Marketplace API

The SmartRecruiters marketplace offers the best recruiting services to our customers and the Marketplace API provides our partners with a platform to integrate these services into our marketplace. Marketplace services include Recruitment Process Outsourcing, Job Boards, Applications, and Assessments.

The Marketplace API is a REST API created for application developers to enable seamless integration with our SmartRecruiters platform. It is divided into several components:

• Application API – Exposes the full candidate application, allows new applications to be submitted, and exposes the status of previously submitted applications.
• Offer API – Allows partners to create and manage offers.
• Assessment API – Enables assessment and screening vendors to receive assessment requests and submit assessment results.
• In-line Assessment API – Allows partners to provide instant assessments embedded right in the candidate application process.
• Job Board API – Allows job board vendors to integrate with SmartRecruiters Marketplaces.

The following sections describe how to connect and interact with the API.

Integration options

Currently, partners have 4 ways of integrating with SmartRecruiters customers:

• Legacy Partner Portal solution - please check the Partner API Key page for more details.
• oAuth Authorization Code credentials - authentication flow in which partners get Customer Level Credentials that act on behalf of a Regular User
• oAuth Client Credentials - SmartRecruiters customer Administrator generate Customer Level Credentials (that act on behalf of a privileged System User) and share it with partner
• oAuth Client Credentials - partner gets Partner Level Credentials from Partner Support Team as an entry step to Assessment (2021) integration flow

Supported Formats

All requests and responses in the Assessment and Offer APIs use JSON by default.
Job Board API uses XML format.

Error Handling

Marketplace API supports the following HTTP error codes:

• 200 – OK
• 400 – Bad Request
• 500 – Internal Server Error

Apart from these three base HTTP codes, Marketplace API request might also return:

• 404 – Not Found
• 401 – Unauthorized
• 403 – Forbidden

Error responses will also contain the following parts:

• id – unique, random generated id that will identify this error occurrence
• httpCode – httpCode associated with a response
• code – internal Marketplace API error code
• message – plain text message describing the error.
• helpUrl – link to error page description
• Please refer to Error object for details.

Please refer to Error object for details.

Example error response:

{    
    "id" : "a08bee84-e056-4d17-b198-03a05ee3cbdb",
    "httpCode": "400",
    "code": "invalid_industry",
    "message": "Industry id is invalid: computer_scienc",
    "helpUrl": "https://api.smartrecruiters.com/v1/errors/invalid_industry"
}

Versioning

Marketplace API requires a version to be specified in every request. Version needs to be placed immediately after our base URL: https://api.smartrecruiters.com/v1. An example URL accessing offer with id 511a3942300469a9c33819d8 using API version 1 will be:

https://api.smartrecruiters.com/v1/offers/511a3942300469a9c33819d8

Currency

Currency values contain two parts – currency code and amount. Currency code will always be a 3 letter ISO 4217 currency representation. Amount will be presented as a string with dot (.) as a decimal separator. Marketplace API will NOT use any locale specific formatting rules. Please refer to Money object for details.

Example currency value for US Dollars:

{
    "amount": "20.00",
    "currencyCode": "USD"
}

Date and Time

All Date and DateTime fields will be formatted according to ISO 8601 standard. All dates with associated time zones will be given in UTC time zone. Date and Time values will be separated with the letter “T”. Time zone offset will be specified as +0000 (UTC time zone).

Example:

{
  "expirationDate": "2013-02-26T12:50:02.594+0000"
}

Geocoding

The API would often require you to specify geographic locations. Location objects can consist of three parts: country, region and city. Not all of these values are mandatory. Please refer to Location object for details. Here are examples that define location objects for different scenarios.

Defining Location object to specify a country (USA)

{
  "country": "US",
}

Location object to specify a state (California)

{
    "country" : "US",
    "region" : "CA"
}

Location object to specify a city (San Francisco)

{
    "country" : "US",
    "region" : "CA",
    "city" : "San Francisco"
}