API Documentation

The Eightfold API provides programmatic access to the Eightfold application. Software developers will be able to build applications leveraging the core Eightfold platform.

Why Rest?

REST provides better features, faster development, and scalable operations.

Better features:

• REST is simpler, faster, and supports more data formats like JSON.
• For that reason it uses less bandwidth and is more compatible with more browser clients.
• Request and response are better structured.
• Response have related data to enable subsequent navigation requests.
• Updates to individual fields instead of posting the entire record.
• Responses can do search and filter in batch.

Faster development and scalable operations:

• Integration code builds faster.
• Browsers including mobile browser can support integrations.
• REST is scalable and stateless.

Authentication

The Eightfold API v2 service is a set of APIs on a separate endpoint than Eightfold API v1. This API service exposes Eightfold core data entities through RESTful APIs. To enable customer integrations, these APIs can be used both to inject and fetch data from Eightfold and other ATS, HRIS, and LMS ecosystems.

📘

How to Enable OAuth for an API Server

Read the step-by-step guide here.

API v1 and v2 comparison

This section describes the main differences between Eightfold API v1 and API v2.

1. Core Eightfold entities are now exposed through the API layer

All core Eightfold entities are now exposed through the API layer, along with ATS and HRIS entities. This enables users to directly create these entities (for example, profiles) without any ATS or HRIS data. This helps users build independent systems on top of the Eightfold ecosystem without a need for another system.

2. All the APIs are now RESTful

RESTful APIs allow Eightfold APIs to be format agnostic. Because there is an independent client and server, Eightfold API v2 is more globally standardized and easier to consume as compared to v1.

3. Support for PATCH operations

Eightfold API v2 supports PATCH operations on most of our entities, a functionality that was not supported in v1. This allows users to only update what's changed, increasing efficiency for change management.

4. Rich entity schema

The API v2 entity schema is richer than v1, allowing for more information and better control during integration with Eightfold systems.

5. Async update support

Support for async updates enables users to post an update and asynchronous return to check the status of the update. This gives more flexibility to users and also allows them to verify data consistency.

6. Name spacing in APIs

Name spacing of the APIs in v2 allows users to quickly discover entities and capabilities. This increases ease-of-use for consuming APIs.

Top level differences in API v1 and v2 APIs

For a quick summary of the v2 APIs in comparison to v1 APIs please refer to the below table. The table summarizes the function of the API entities.

API v2 uses OAuth 2.0 authentication, making it more secure. This allows our clients to satisfy a high level of security compliance standards.

API service V2 FAQs

Here are the frequently asked questions related to API v2 Services

1. Can we continue using the Eightfold API v1 service?

Existing customers can continue using API service v1 until they can make the necessary changes to migrate to v2. We recommend moving to v2 as soon as possible to be able to use the full API service capabilities of Eightfold.

2. Will feature enhancements be supported for v1 for existing APIs?

Mostly no. We will avoid enhancing any feature of Eightfold API v1 and are moving API v1 servie to deprecated support. For critical scenarios, customers can engage with the team to assess their use case.

3. Will there be support for bug fixes on v1?

Yes, we will give standard support, which we are providing currently with bug fixes, until the v1 deprecation.

4. What is the approximate timeline for depreciation of v1?

The team is estimating a complete deprecation of the Eightfold v1 API service by end-of-year 2022.

5. Does API v2 have a similar rate limitation of APIs as there was in API v1?

Yes, Eightfold API v1 and v2 have similar rate limitations of the individual APIs.

Best Practices

We list below a few best practices to help you in your development:

• Include HTTP headers: Content-Type, Content-Length, and Request-Id. Request-Id will help us in preventing duplication of ingestion.
• Chunk large payloads: Payloads larger than 15 MB will result in HTTP 413 error RequestEntityTooLarge. Chunk the request so that the payload is under this limit.
• Retry requests: Successful submissions will return 200 OK. Retry the request on error approximately 3 times with a sleep of 10 seconds.
• Daily batch updates: Send updates for all open positions in a daily batch updates to ensure no updates are missed.

API Limits

API Rate Limits and Throttling
Eightfold supports 100 requests per minute for an account. After this limit, Eightfold will respond with a HTTP 429 Too Many Requests error.
For some endpoints that return multiple records such as Candidates:Get Matching Jobs, Employee:Get Matching Jobs by Email, Position:Get Matching Candidates, Position:Get Applicants and Search Candidates, the rate limit is 20 requests per minute for an account.

Pagination
Eightfold supports the start and limit parameters in listing type APIs. The API response will return a maximum of 100 results per page. The default is 5 results in a response.
Eightfold returns a maximum of 100,000 results for applicants and candidate searches sorted by Eightfold profile ID, and 1000 results for Match Score based APIs such as matching leads. Specifically, the start and limit parameters should be no higher than the maximum allowed.

The filterQuery parameter

Eightfold API such as Search Candidate, Search Position, and Get Applicants support the filterQuery parameter.

1. Boolean operators such as (), AND, OR, and negation are supported.
2. Timestamps are in epoch time for example 1599879364 for September 12, 2020 2:56:04 AM UTC.
3. Time ranges can be specified as [1599879364 TO *] for time after the timestamp, [* TO 1599879364] for times before the timestamp, or [1598879364 TO 1599879364] for times in between timestamps

Here is an example to search for candidates saved for a position with ID 1234 but have not applied or been contacted.
(savedFor:1234 AND (-contactedFor:1234 OR -appliedFor:1234))

Candidate field query parameters are listed below.

Position field query parameters are listed below.

Demand field query parameters are listed below.

Org Unit field query parameters are listed below.

Error codes

Following is the list of error codes that the user might come across while making API requests.