---
name: turatalent
version: 1.0.0
description: Hiring pipeline API. Post jobs, track candidates through stages, schedule interviews. Structured recruiting over REST.
homepage: https://www.turatalent.com
metadata: {"category":"hr","api_base":"https://www.turatalent.com/api/v1"}
---

# TuraTalent

**Hiring pipeline via API.**

Post jobs, collect applications, move candidates through custom stages, and schedule interviews — all over REST. Part of Tura Cloud. Authentication uses TuraLogin API keys (Bearer token).

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://www.turatalent.com/SKILL.md` |
| **AGENTS.md** | `https://www.turatalent.com/AGENTS.md` |
| **API.md** | `https://www.turatalent.com/API.md` |
| **QUICKSTART.md** | `https://www.turatalent.com/QUICKSTART.md` |
| **skill.json** (metadata) | `https://www.turatalent.com/skill.json` |

**Base URL:** `https://www.turatalent.com/api/v1`

**Authentication:** `Authorization: Bearer <API_KEY>` — Use TuraLogin API keys from https://www.turalogin.com/dashboard/keys

---

## Overview

TuraTalent is a structured hiring pipeline:

✅ **Job postings** — Create, publish, and manage job listings  
✅ **Applications** — Collect applicants with their details  
✅ **Pipeline stages** — Move candidates through custom stages  
✅ **Interviews** — Generate scheduling links and track confirmed slots  

You handle:
- Careers page UI and public job listing
- Candidate communication and email outreach (use TuraText)
- Internal team notes and discussion
- Offer letter generation

---

## Quick Start

### 1. Get Your API Key

TuraTalent uses **TuraLogin API keys**. Get one at https://www.turalogin.com/dashboard/keys

- Test: `tl_test_xxxxxxxxxxxxxxxx`
- Production: `tl_live_xxxxxxxxxxxxxxxx`

### 2. Create a Job Posting

```bash
curl -X POST https://www.turatalent.com/api/v1/talent/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Engineer",
    "description": "Build the product from 0 to 1.",
    "location": "Remote",
    "type": "full-time",
    "department": "Engineering"
  }'
```

**Response:**
```json
{
  "id": "job_abc123xyz",
  "title": "Senior Engineer",
  "location": "Remote",
  "type": "full-time",
  "department": "Engineering",
  "status": "draft",
  "applicationCount": 0,
  "createdAt": "2026-02-22T10:00:00Z"
}
```

### 3. Submit an Application

```bash
curl -X POST https://www.turatalent.com/api/v1/talent/applications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "job_abc123xyz",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "resumeUrl": "https://cdn.example.com/resume.pdf"
  }'
```

---

## Full API Reference

### POST /api/v1/talent/jobs

Create a job posting.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Job title |
| `description` | string | Yes | Full job description (markdown supported) |
| `location` | string | Yes | Location or `Remote` |
| `type` | string | Yes | `full-time`, `part-time`, `contract`, `internship` |
| `department` | string | No | Department name |
| `compensation` | string | No | Salary range or `Competitive` |
| `status` | string | No | `draft` or `published` (default: `draft`) |

---

### GET /api/v1/talent/jobs

List job postings.

**Query Parameters:** `status` (`draft`, `published`, `closed`), `department`, `limit`, `cursor`

---

### PATCH /api/v1/talent/jobs/:id

Update a job (publish, close, edit fields).

---

### POST /api/v1/talent/applications

Submit a candidate application.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `jobId` | string | Yes | Job being applied to |
| `name` | string | Yes | Candidate name |
| `email` | string | Yes | Candidate email |
| `resumeUrl` | string | No | Link to resume/CV |
| `coverLetter` | string | No | Cover letter text |
| `linkedinUrl` | string | No | LinkedIn profile |
| `answers` | object | No | Custom question answers |

**Success Response (201):**
```json
{
  "id": "app_abc123xyz",
  "jobId": "job_abc123xyz",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "stage": "applied",
  "createdAt": "2026-02-22T10:00:00Z"
}
```

---

### GET /api/v1/talent/applications

List candidates with pipeline stage.

**Query Parameters:** `jobId`, `stage`, `limit`, `cursor`

---

### PATCH /api/v1/talent/applications/:id

Move a candidate to a new stage.

**Request Body:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `stage` | string | `applied`, `screening`, `interview`, `offer`, `rejected`, `hired` |
| `notes` | string | Internal notes |

---

### POST /api/v1/talent/interviews

Schedule an interview.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `applicationId` | string | Yes | Candidate application |
| `scheduledAt` | string | Yes | ISO 8601 datetime |
| `duration` | number | No | Minutes (default: 60) |
| `type` | string | No | `video`, `phone`, `onsite` |
| `interviewers` | string[] | No | Interviewer emails |

---

### GET /api/v1/talent/stats

Get hiring pipeline stats.

**Success Response (200):**
```json
{
  "totalApplications": 84,
  "byStage": {
    "applied": 40,
    "screening": 20,
    "interview": 15,
    "offer": 5,
    "hired": 3,
    "rejected": 1
  },
  "openJobs": 4
}
```

---

## Framework Examples

### Next.js (App Router)

```typescript
// app/api/talent/jobs/route.ts
export async function POST(request: Request) {
  const body = await request.json();

  const res = await fetch('https://www.turatalent.com/api/v1/talent/jobs', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TURATALENT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  return Response.json(await res.json(), { status: res.status });
}

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);

  const res = await fetch(
    `https://www.turatalent.com/api/v1/talent/jobs?${searchParams.toString()}`,
    { headers: { 'Authorization': `Bearer ${process.env.TURATALENT_API_KEY}` } }
  );

  return Response.json(await res.json());
}
```

---

## Error Codes

| Status | Error | Description |
|--------|-------|-------------|
| 400 | `title is required` | Missing job title |
| 400 | `Invalid type` | Must be full-time, part-time, contract, or internship |
| 400 | `Invalid stage` | Must be a valid pipeline stage |
| 401 | `Unauthorized` | Missing or invalid API key |
| 404 | `Job not found` | Invalid job ID |
| 404 | `Application not found` | Invalid application ID |
| 409 | `Already applied` | Duplicate application for same email + job |
| 429 | `Too many requests` | Rate limit exceeded |

---

## Support & Resources

- 🌐 Website: https://www.turatalent.com
- 🔑 API Keys: https://www.turalogin.com/dashboard/keys