REST API

Unitity AI API

v1 · Base URL: https://unitityai.com/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. Generate tokens in your workspace Settings → API Tokens.

# All requests must include:
Authorization: Bearer uai_your_token_here
Content-Type: application/json

candidates:read— List and read candidate profiles

candidates:write— Create and update candidates

requisitions:read— List open requisitions

pipeline:read— Read stage counts and stuck alerts

pipeline:write— Advance candidate stages

*— Full access (admin only)

Candidates

GET

/api/v1/candidates

List all candidates in your pipeline.

Parameters

stage	string	optional	Filter by stage: applied, ai_screened, interview_scheduled, interviewed, offer_sent, offer_accepted, onboarding, placed
req_id	string	optional	Filter by requisition UUID
limit	integer	optional	Max results (default 50, max 200)
offset	integer	optional	Pagination offset

Example Response

{
  "data": [
    {
      "id": "a1b2c3...",
      "name": "Jordan Rivera",
      "email": "j.rivera@email.com",
      "phone": "720-555-0101",
      "stage": "interview_scheduled",
      "resume_url": "https://...",
      "req_title": "Sr. Solar Sales Engineer",
      "req_id": "d4e5f6...",
      "created_at": "2026-07-02T08:44:00Z",
      "updated_at": "2026-07-06T09:14:00Z"
    }
  ],
  "count": 1,
  "offset": 0,
  "limit": 50
}

POST

/api/v1/candidates

Create a new candidate in your pipeline. Useful for syncing from your ATS or CRM.

Parameters

name	string	required	Full name
email	string	optional	Email address
phone	string	optional	Phone number
req_id	string	optional	Requisition UUID to assign candidate to
stage	string	optional	Initial stage (default: applied)

Example Response

{
  "data": {
    "id": "a1b2c3...",
    "name": "Alex Johnson",
    "email": "alex@example.com",
    "stage": "applied",
    "created_at": "2026-07-07T20:00:00Z"
  }
}

Requisitions

GET

/api/v1/requisitions

List requisitions with candidate counts.

Parameters

status	string	optional	open (default), on_hold, filled, draft, closed
limit	integer	optional	Max results (default 50, max 200)

Example Response

{
  "data": [
    {
      "id": "req_uuid",
      "title": "Sr. Solar Sales Engineer",
      "department": "Sales",
      "location": "Castle Rock, CO",
      "job_type": "direct_hire",
      "status": "open",
      "candidate_count": "12",
      "offers_pending": "1",
      "created_at": "2026-07-01T00:00:00Z"
    }
  ],
  "count": 1
}

Pipeline

GET

/api/v1/pipeline

Get pipeline stage distribution and stuck candidate alerts.

Example Response

{
  "data": {
    "stage_counts": {
      "applied": 8,
      "ai_screened": 5,
      "interview_scheduled": 3,
      "interviewed": 2,
      "offer_sent": 1
    },
    "total_active": 19,
    "stuck_candidates": [
      {
        "id": "cand_uuid",
        "name": "Marcus Webb",
        "stage": "ai_screened",
        "days_in_stage": 8,
        "req_title": "Sr. Solar Sales Engineer"
      }
    ]
  }
}

POST

/api/v1/pipeline

Advance or change a candidate's pipeline stage.

Parameters

candidate_id	string	required	Candidate UUID
stage	string	required	Target stage: applied, ai_screened, interview_scheduled, interviewed, offer_sent, offer_accepted, onboarding, placed, rejected

Example Response

{
  "data": {
    "id": "cand_uuid",
    "name": "Marcus Webb",
    "stage": "interview_scheduled",
    "updated_at": "2026-07-07T20:30:00Z"
  }
}

Error Codes

401UnauthorizedMissing or invalid API token

403ForbiddenValid token but missing required scope

404Not FoundResource does not exist in your tenant

400Bad RequestMissing or invalid request parameters

500Server ErrorInternal error — contact support

# All errors return:
{
  "error": "Human-readable error message"
}

Quick Start

# 1. Get your pipeline overview
curl https://unitityai.com/api/v1/pipeline \
  -H "Authorization: Bearer uai_your_token"

# 2. List candidates in interview stage
curl "https://unitityai.com/api/v1/candidates?stage=interview_scheduled" \
  -H "Authorization: Bearer uai_your_token"

# 3. Push a candidate from your CRM
curl -X POST https://unitityai.com/api/v1/candidates \
  -H "Authorization: Bearer uai_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex Johnson","email":"alex@co.com","stage":"applied"}'

# 4. Advance a candidate's stage
curl -X POST https://unitityai.com/api/v1/pipeline \
  -H "Authorization: Bearer uai_your_token" \
  -H "Content-Type: application/json" \
  -d '{"candidate_id":"uuid-here","stage":"interviewed"}'

Unitity AI API v1 · Manage your tokens