# Quickstart

This guide takes you from credentials to your first published job. You need a **test client secret**
(it starts with `aiv_test_`) and a **tenant ID**. If you don't have them yet, email
[partners@aiviue.com](mailto:partners@aiviue.com).

All requests go to the base URL `https://api.aiviue.com`. Paths start with `/v1`.

## 1. Check connectivity

The health endpoint needs no credentials:

```bash
curl https://api.aiviue.com/v1/integration/health
```

## 2. Get an access token

Exchange your client secret for a short-lived bearer token (OAuth 2.0 client credentials). With a prefixed
secret you can leave `client_id` out.

```bash
curl -X POST https://api.aiviue.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials", "client_secret": "aiv_test_..."}'
```

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "jobs:read jobs:write candidates:read webhooks:read webhooks:write"
}
```

Tokens last one hour. Cache the token and request a new one shortly before it expires. See
[Authentication](/developers/guides/authentication).

## 3. Publish a job

Every resource call carries three headers:

- `Authorization: Bearer <access_token>`
- `X-Tenant-ID: <tenant id>` — which of your customers this job belongs to ([Tenants](/developers/guides/tenants))
- `X-Idempotency-Key: <unique key>` — required on every write ([Idempotency](/developers/guides/idempotency))

```bash
curl -X POST https://api.aiviue.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Idempotency-Key: create-job-REQ-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "external_job_id": "REQ-1042",
    "title": "Delivery Executive",
    "description": "Deliver orders across Koramangala. Two-wheeler and licence required.",
    "openings": 5,
    "location": {"city": "Bengaluru", "state": "Karnataka", "country": "IN"}
  }'
```

`external_job_id` is your own stable ID for the job. `title` and a `description` of at least 10 characters are
required unless you send a `jd_url` instead.

The response uses the standard envelope:

```json
{
  "success": true,
  "data": {
    "job_id": "...",
    "external_job_id": "REQ-1042",
    "campaign_id": "...",
    "status": "...",
    "aiviue_url": "https://...",
    "created_at": "2026-11-02T10:00:00Z"
  },
  "meta": { "requestId": "...", "timestamp": "...", "version": "1.0" }
}
```

## 4. Receive candidates

Aiviue now runs the campaign and screens applicants. To get results:

- **Webhooks (recommended):** subscribe to events such as `screening.completed` — see [Webhooks](/developers/guides/webhooks).
- **Polling:** `GET /v1/jobs/{job_id}/candidates`, then `GET /v1/candidates/{candidate_id}` and `/scores`.

## Next steps

- Browse every endpoint in the [API reference](/developers/api-reference).
- Try the full flow end to end in the [Sandbox](/developers/guides/sandbox).