Introduction

Use the Sense API to synchronize your ATS data into the Sense Platform. The RESTFUL API is used to seed the initial set of entities and keep them up-to-date over time. Synchronizing data into Sense is what powers the automation of Sense Workflows.

Our API definition uses the OpenAPI 3.0 specification. You can download the definition and create a client library using the openapi-generator project.

Authenticate to the Sense API using OAuth2 client credentials. The Sense Team will provide you with credentials that will synchronize data to your account at your-agency-name.sensehq.com.

IMPORTANT: Clients must cache and reuse access tokens until they expire, as indicated by the expires_in field in the token response.

Sample Token Response

{
  "access_token": "eyJr...",
  "expires_in": 300,
  "token_type": "Bearer"
}

To ensure stable, efficient, and compliant integrations with the Sense API, follow these best practices:

• Cache the access token securely and reuse it for all requests until it expires.
• Always respect the expires_in field returned in the token response.

  ⚠️ Do not hardcode the expiry time (e.g., 5 minutes). While the current token lifetime is 300 seconds (5 minutes), it may change in the future without notice. Your integration should dynamically honor the expires_in value provided.

• Only request a new token when the existing one is about to expire.
• Avoid calling the token endpoint unnecessarily — doing so may lead to rate limiting or deactivation.
• Implement retry logic with exponential backoff in case of transient failures.
• Monitor your integration for abnormal token request patterns.

Following these practices ensures better reliability, reduces infrastructure strain, and prevents disruptions to your access.

Depending on your tech stack, here are some guides and libraries to help implement OAuth token caching:

General

• RFC 6749 - OAuth 2.0 Specification (Section 1.5)
• Understanding OAuth Access Token Lifetime

Node.js

• Simple OAuth2 Library (with built-in caching)

Python

• Requests-OAuthlib (with token storage example)

Java

• Spring Security OAuth2 (with in-memory token caching)
• Google HTTP Client Library for OAuth 2.0

Postman

• Postman Environment Variable Token Reuse Guide

Implement token caching early in your integration lifecycle to ensure your application is efficient and remains in good standing with Sense API rate limits.

To synchronize data with Sense, we need the initial seed of entity data (Candidates, Placements, etc), and updates to those entities over time. To accomplish this, we recommend two processes named Sync and Change Event.

When data is sent and accepted by the Sense API, the data is enqueued to be processed by Sense's background processes. You should expect data to be visible in the Sense product 30 minutes after your API call for Change Event processes.

Sync Process

The sync is generally a long running process that iterates over your entire data set and calls the Sense API. For example, to sync a database of 1 million candidates, POST to the /candidates endpoint in batches of 500 under 256 kb after compression.

Change Event Process

To keep the initial set of data up-to-date, the Change Event process can be implemented as a hook whenever your entities change. You can call the Sense API POST /candidates when any of the fields defined in the Candidate model change. To take advantage of batching (our API supports 500 updates at a time under 256 kb after compression), your Change Event process can flush changes to the Sense API after it accumulates 500 updates, exceeds 256 kb after compression or after 5 minutes, whichever comes first.

Sync Operation

• Currently, all API POST methods are treated as UPSERT operations. The expectation is that you provide the complete entity, and it will be created or updated (i.e. replacing the content for an existing id). Take care that all fields are provided.

• A soft DELETE Operation is supported if the entity payload is sent with the field is_deleted = true.

• To prevent referencing a foreign key that has not been processed yet sync the following entities in this order:

  • https://partner-api.sensehq.com/v1/internal-users

  • https://partner-api.sensehq.com/v1/candidates

  • https://partner-api.sensehq.com/v1/client-contacts

  • https://partner-api.sensehq.com/v1/companies

  • https://partner-api.sensehq.com/v1/job-orders

  • https://partner-api.sensehq.com/v1/submissions

  • https://partner-api.sensehq.com/v1/placements

  • https://partner-api.sensehq.com/v1/leads

Considerations

• Record the time the Sync Process started as the timestamp to query for changed entities, then use it in your Change Event process to get all changes since that timestamp so no updates are missed.
• The entity data must be complete. When an entity is sent to the API, it's treated as an UPSERT operation - the old version of the entity is replaced with the new version.

Entity types

Candidate

A person seeking a job.

Placement

A job that has been filled by a Candidate.

InternalUser

An internal person at your organization.

JobOrder

A job to be filled by a Candidate.

Company

A company that is a client of your organization.

ClientContact

A contact person at a Company.

Appointment

An interview or a meeting with a Candidate or Contact.

Submission

Sending a Candidate’s info for additional review.

Certification

The credential and or certificate of Candidate, or as required by a Job.

Lead

A new prospective client or contact

 

Field types

id

Primary key of the entity. This represents the ID in your system and is not managed by Sense. All ids are treated as strings.

• Nullable: True
• Examples
  • Candidate Entity: { "id": "123", "first_name": "Linus", ... }

int, float, string

• Nullable: True
• Examples
  • 1, 1.0, "hello world"

datetime

• Nullable: True
• Format: ISO 8601
• Strict Validation: If a datetime field is unable to be parsed in ISO 8601 format, the update is rejected and the API will return a 400 Bad Request.
• Examples
  • 2020-04-01T10:30:00+0000 is 2020-04-01 at 10:30 AM UTC.
  • 2020-04-01T10:30:00-0700 is 2020-04-01 at 10:30 AM Pacific.

ref

Represents a primary key reference to another entity.

• Nullable: True
• Format: string
• Examples:
  • A field named "internal_user_id" on Placement points to an InternalUser by its primary key.
    • Placement Entity: { "id": "123", "internal_user_id": "456", "status": "Active", ... }
    • Internal User Entity: { "id": "456", "first_name": "Ace" }

Post a Candidate Entity

import requests

# Obtain a Bearer token using your client credentials.
auth_response = requests.post(
    "https://partner-auth.sensehq.com/oauth2/token",
    data={
        "client_id": "client_id",
        "client_secret": "client_secret",
        "grant_type": "client_credentials",
    },
)
assert auth_response.status_code == 200
print("Authenticated successfully.")

# Post a Candidate entity.
bearer_token = auth_response.json()["access_token"]
response = requests.post(
    "https://partner-api.sensehq.com/v1/candidates",
    json=[{
        "id": "123",
        "first_name": "Linus",
        "last_name": "Kerns",
        "email": "linus@sensehq.com",
        "mobile_phone": "(415) 555-1234",
        "status": "Active",
    }],
    headers={"Authorization": f"Bearer {bearer_token}"},
)
assert response.status_code == 201
print("Posted Candidate successfully.")

 

Update a Candidate Entity

import requests

# Obtain a Bearer token using your client credentials.
auth_response = requests.post(
    "https://partner-auth.sensehq.com/oauth2/token",
    data={
        "client_id": "client_id",
        "client_secret": "client_secret",
        "grant_type": "client_credentials",
    },
)
assert auth_response.status_code == 200
print("Authenticated successfully.")

# Update a Candidate entity.
bearer_token = auth_response.json()["access_token"]
resource_id = 123
response = requests.patch(
    f"https://partner-api.sensehq.com/v1/candidates/{resource_id}",
    json={
        "status": "InActive",
    },
    headers={"Authorization": f"Bearer {bearer_token}"},
)
assert response.status_code == 201
print("Updated Candidate successfully.")

 

Fetch a Candidate Entity

import requests

# Obtain a Bearer token using your client credentials.
auth_response = requests.post(
    "https://partner-auth.sensehq.com/oauth2/token",
    data={
        "client_id": "client_id",
        "client_secret": "client_secret",
        "grant_type": "client_credentials",
    },
)
assert auth_response.status_code == 200
print("Authenticated successfully.")

# Get a Candidate entity.
bearer_token = auth_response.json()["access_token"]
resource_id = 123

get_api_response = requests.get(f"https://partner-api.sensehq.com/v1/candidates/{resource_id}",
    headers={"Authorization": f"Bearer {bearer_token}"},)

assert get_api_response.status_code == 200
print(f"Fetched candidate successfully")

Authenticate using client credentials to obtain a Bearer access_token.

An interview or a meeting with a Candidate or Contact.

A person seeking a job.