Data Import

How to persist data into Endorsed for import and processing.

Data Import involves persisting data in the following order. Please refer to the corresponding API references for how to make the API calls.

  1. Jobs [API Reference]

  2. Nomination Stages [API Reference]

  3. Candidates [API Reference]

  4. Nominations [API Reference]

  5. Attachments [API Reference]

All entities have REST endpoints to create, read, or update except for Attachments which are immutable after upload.

Import Guidelines

In most cases, Endorsed's data import endpoints should not be used as Source of Truth.

The Data Import endpoints mainly enable Endorsed to support filtering, AI-based ranking, and summary generation for queries. While GET import endpoints exist mainly for debugging, they shouldn't typically serve as the Source of Truth, as your database often aligns more closely with application-specific business logic and is more up-to-date. For questions or if you considering using Endorsed as a Source of Truth, contact our team at support@endorsed.ai.

Jobs

Execute calls to the create API on the Jobs endpoint. See API Reference for more details.

Nomination Stage Configuration

Nomination Stages for a given job represent an ordered sequence of states through which an nomination can progress. A Job has a 1-many relationship to Nomination Stages. Execute calls to the create API on the Nomination Stages endpoint. See API Reference for more details.

Let's take an example. Suppose we have a Job named Email Marketing Manager with the following stages ordered from left to right.

After the job has been persisted, each corresponding Nomination Stage should be persisted with the `job_id` against the Nomination Stages API such that they can be associated with a nomination. An Nomination MUST be in a valid existing Nomination Stage at all points in time.

Each Nomination Stage has a corresponding stage_order_index number field that represents it's order within the sequence. For the same example, valid indices could look like the following:

Functional Order
Nomination Stage Name
Stage Order Index

1

Unreviewed

1000

2

Rejected

2000

3

Holding

3000

4

Advancing

4000

Requirements / Guidance:

  • Each Nomination Stage within the same job MUST have a unique stage_order_index. We validate this on create / update

  • It is encouraged to create significant sufficient space between stage order indices to allow for inserting new stages in the future. For example, two indices of 1000 and 2000 may simpler to insert an intermediate stage at 1500 while two indices of 1 and 2 may require data migration to insert a new stage in between.

  • We recommend persisting the returned Job id in your system for future decoration / querying purposes.

See Nomination Stages API Reference for request / response details.

Candidate Import

A candidate represents an individual that can potentially apply to job. Execute calls to the create API on the Candidates endpoint. See API Reference for more details.

Requirements / Guidance:

  • We recommend persisting the returned Candidate id in your system for future decoration / querying purposes.

Nomination Import

Nominations represent a candidate and their corresponding nominations to a given job. A nomination can represent either an application of a candidate who has actively applied for a job OR an active consideration of a candidate for a job by a recruiter, marketplace, etc. Generally, a nomination can be thought of as any explicit association that should be made between a candidate and a job regardless of which person, organization, or entity initiated the creation of that association. A job has a 1-many relationship with nominations. A candidate has a 1-many relationship with nominations. Execute calls to the create API on the Nominations endpoint. See API Reference for more details.

Requirements / Guidance:

  • Each nomination MUST have a valid existing Nomination Stage id in the current_nomination_stage_id for the corresponding job that the nomination applies to.

  • Nominations current Nomination Stage can be updated according to how they progress across the stages throughout the nomination and interview stage process.

  • We recommend persisting the returned Nomination id in your system for future decoration / querying purposes.

Attachment Upload

An attachment represents a successfully uploaded file (resume, cover letter, etc.) that is associated with a candidate. Only rare scenarios (lookalike search) should not be associated with a candidate where a candidate can have many attachments.

Execute calls to the API on the Attachments endpoint. See. API Reference for more details.

Requirements / Guidance:

  • In a vast majority of cases, ensure to pass the candidate_id into the attachments upload API to ensure that the attachment can be imported and processed by Endorsed such that they can be queried upon for ranking and summaries.

  • We recommend persisting the returned Attachment id in your system for future decoration / querying purposes.

Post-Import

After import, Endorsed will process all nominations and attachments such that they can be summarized and queried upon. SLAs for processing are dependent upon your pricing plan and sales agreement. Reference the following pages for:

Last updated