SmartSearch Platform API

Getting Started

The SmartSearch Platform API provides many tools and resources that enable you to integrate with all the powerful capabilities within SmartSearch.

API Key

To start using the SmartSearch Platform API, you must use a valid API Key to send requests to the API endpoints.

• You can get your API key by emailing integrations@smartsearchinc.com
• If you are creating an integration for a specific SmartSearch customer, please reach out to them so they can request the API Key for you

HTTPS Only

• The API only responds to HTTPS-secured communications
• Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources

Response Format

• The API returns request responses in JSON format
• When an API request returns an error, it is sent in the JSON response as an error key

Authentication

The SmartSearch Platform API uses bearer tokens for authentication.

Generating a Bearer Token

To generate a bearer token, you must make an authentication request to the account endpoint with the X-API-KEY request header and your API user and password in the request body.

POST /accounts
X-API-KEY: your-api-key-here
Content-Type: application/json

{
  "userName": "your-username",
  "password": "your-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the Bearer Token

Include the bearer token in the Authorization header for all subsequent requests:

GET /candidates
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication Error Response

If the bearer token is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.

Additional Notes

OData & JSON Patch

The GET endpoints in the SmartSearch Platform API follow the OData standard while the PATCH endpoints utilize the JSON Patch format.

Important: PATCH requests require the Content-Type: application/json-patch+json header.

Pagination

By default, the Platform API returns 1,000 records at any given time. If there are more than 1,000 results, it returns a link to get the next set of results.

Timestamps

All incoming timestamps in the SmartSearch Platform API must follow the ISO 8601 format. Below are examples of valid timestamp formats you may encounter or use:

• UTC timestamp: 2024-08-15T14:30:00Z
• Date-only format: 2024-08-15

Important: When sending timestamp data in requests, ensure it adheres to the ISO 8601 standard. If no timezone is specified, UTC is assumed by default.

Need Some Help?

In case you have questions, please email integrations@smartsearchinc.com.