API Overview

The Data Ingestion API is a RESTful API that enables efficient management of workforce data at scale through batch operations. You can create, update, and delete employee records in bulk, monitor progress.

Beyond data management, this API enables you to leverage our AI-powered job classification model, which classifies your workforce data against our bespoke ontology framework. By using this API, you enrich your proprietary data with our comprehensive skills and tasks datasets, providing deeper insights and enhancing your workforce analytics.

It is ideal for organizations dealing with large employee datasets, continuous data updates, and system integrations.

Intended Audience

This API is intended for software developers with experience in:

• RESTful API
• JSON formatting
• HTTP request handling
• API authentications (e.g., API keys or bearer tokens)

Prerequisites

All requests to this API must be authenticated using a valid API key. API keys are used to associate requests with your account and authorize access to specific resources.

Using the API Key

Include the API key in the Authorization header for every request:

Authorization: Bearer YOUR_API_KEY 

Example Request:

GET /v1/batches HTTP/1.1
Host: https://au.aws.api.faethm.ai/
Authorization: Bearer 7Gf39B8jKTpZxWuYv5Qk4eLxN3dDf0aP

NOTE This is a standard API key. Your actual key will look similar to the value shown above. While the value will be unique per user, the structure and encoding format will remain the same.

Best Practices for Secure API Key Usage

• Never expose API keys in client-side code (JavaScript, HTML)
• Restrict key access by environment or IP address if supported
• Store keys securely using environment variables or secrets managers (e.g. AWS Secrets Manager, Vault)

Key Use-Cases & Benefits

• Bulk operations: Manage thousands of employee records efficiently.
• Real-time monitoring: Track the progress of batch uploads and updates.
• Progressive uploads: Update data incrementally as it changes.
• Workforce classification: Apply job classification AI models to normalize your workforce data against Pearson Ontology framework.
• System integration: Sync employee data across HR with our automated classification service.

High Level Diagram

Key Capabilities

• Bulk Employee Data Uploading - API developers can send a large number of employees from your HR system for job classification.
  • Use the Create batch endpoint to start a batch.
  • Upload records using the Populate batch endpoint.
  • Monitor progress with the Batch monitoring endpoint.
• Progressive Data Uploading- Update employee records continuously as changes occur.
  • Initiate a batch using the Create batch endpoint.
  • Incrementally upload changes via the Progressive uploading endpoint.
  • Track updates using the Batch monitoring endpoint.
• Batch Monitoring - Enable developers to monitor batch processes complete without issues.
  • Create and populate a batch using Create batch and Populate batch.
  • Start processing with Process batch.
  • Monitor status and resolve issues with Batch monitoring.
  • Confirm successful processing using the Batch records endpoint.
• Data Synchronization Across Systems - Sync employee data between your HR system and our AI-automated job classification service.
  • Initiate a batch via Create batch.
  • Process synchronization using Process batch.
  • Validate completion using Batch records.

Troubleshooting Guide

This section covers common issues you might encounter while using the API, along with suggested solutions to help you resolve them efficiently.

404 Not Found — "Batch not found"

What it means: The batch_id provided does not match any existing batch in the system.

Possible causes:

• The batch_id is incorrect or malformed
• The batch has been deleted or never existed

How to fix:

• Double-check the batch_id for typos or formatting
• Confirm that the batch was successfully created
• Ensure you're using the correct API environment and credentials

400 Bad Request — "Missing required field"

What it means: One or more required fields are missing in the request body.

Possible causes:

• The JSON payload is incomplete or malformed
• Required fields were omitted, for example, batch_id, batch_type, etc.

How to fix:

• Validate the request body

401 Unauthorized — "Invalid or missing API key"

What it means: The API key is not present, is invalid, or has expired.

Possible causes:

• No Authorization header was provided
• The key used is incorrect or expired
• You are using a test key in a production environment or vice versa

How to fix:

• Check that the Authorization header is formatted correctly:
  The Authorization header must include the word Bearer followed by a space, then your actual API key (token). For example:

Authorization: Bearer 7Gf39B8jKTpZxWuYv5Qk4eLxN3dDf0aP

• Generate a new API key from your account dashboard
• Use the correct key for the appropriate environment

500 Internal Server Error

What it means: An unexpected error occurred on the server.

Possible causes:

• Temporary system issue
• Malformed data edge case

How to fix:

• Retry the request after a few seconds
• If the issue persists, contact support

Changelog & Versioning

This is the first version of our Workforce Classification API.

At this time, we do not have a public changelog or API status page. However, we are committed to transparency and developer trust. In future updates, we will introduce:

• A changelog to document new features, improvements, and breaking changes
• Versioning guidelines to help you migrate between API versions with confidence

🔄

In the meantime, expect that this API may evolve — including changes to endpoints, payloads, or authentication mechanisms

Stay tuned, and thank you for building with us.