---
title: "Create an application"
method: POST
path: "/v1/applications"
tags: ["Applications"]
---

# Create an application

`POST /v1/applications`

## Request

- Base URL: `https://api.yardstick.team`
- URL: `https://api.yardstick.team/v1/applications`
- Auth: HTTP bearer

Create an application

**Required scopes:** `applications:write`

Use this endpoint when a user asks to create or add a candidate for a job. Create or reuse the Person first, then create the Application; the resulting record appears through read-only opportunity views and the app's Candidates surfaces. If the prerequisite Person is unavailable, the response is 404 `person_not_found` with `param: person_id`; if the prerequisite Job Posting is unavailable, it is 404 `job_posting_not_found` with `param: job_posting_id`. A later application read still uses `application_not_found` with `param: application_id`.

**Example (curl):**

```bash
curl -X POST https://api.yardstick.team/v1/applications \
  -H 'Authorization: Bearer ys_sk_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7c3a…' \
  -d '{"person_id":"per_abc123","job_posting_id":"jp_xyz789"}'
```

**Example (TypeScript):**

```ts
await fetch("https://api.yardstick.team/v1/applications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    person_id: "per_abc123",
    job_posting_id: "jp_xyz789",
  }),
});
```

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `person_id` string, required
  - `job_posting_id` string, required

## Response `200`

Success

- Application: Canonical application tying a person to a job posting and hiring workflow. Use this resource when a user asks to create or add a candidate for a job.
  - `is_candidate` boolean, required: Explicitly admitted to the interview process; Review Applications and Candidates are mutually exclusive per application.
  - `candidate_admission_id` string, uuid, nullable, required: Raw current admission UUID, required as expected_admission_id when undoing.
  - `candidate_admitted_at` string, nullable, required
  - `candidate_admission_origin` string, nullable, required
  - `candidate_activity_started_at` string, nullable, required: Non-null after durable candidate activity; undo is then unavailable.
  - `id` string, required: Display id, e.g. `app_<base32>`
  - `object` 'application', required
  - `person_id` string, required: Canonical `per_...` person id.
  - `status` string, required
  - `stage` string, required: Deprecated free-form stage label. Status transitions never change it; read `pipeline_stage_id` for the pipeline position.
  - `pipeline_stage_id` string, nullable, required: Display id (`pst_<base32>`) of the configured pipeline stage (board column) the application sits in; every status transition moves it to the stage mapped to the new status. Null when no configured stage is assigned.
  - `job_id` string, nullable, required: Canonical `job_...` Job id when the application is linked to a Job; null for legacy or unlinked applications.
  - `job_posting_id` string, nullable, required
  - `source` object, required
    - `token_id` string, nullable, required
    - `label` string, nullable, required
  - `livemode` boolean, required
  - `created` string, nullable, required
  - `updated` string, nullable, required
  - `archived_at` string, nullable, required: ISO-8601 UTC; non-null when the application has been archived.
  - `archived_reason` string, nullable, required: Free-text archive reason captured at archive time; nullable.

## Other responses

- `400`: Invalid request
- `401`: Authentication failure
- `403`: Permission denied (scope or feature flag)
- `404`: Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.
- `409`: Conflict (e.g. idempotency key reuse with different body)
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/yardstick/apis/yardstick-public-api.md) · [All operations](https://skmtc.dev/yardstick/apis/yardstick-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yardstick/apis/yardstick-public-api/revisions/bef1d2eaaaa1?raw)