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.

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

1. Check connectivity

The health endpoint needs no credentials:

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.

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

{
  "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.

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)
• X-Idempotency-Key: <unique key> — required on every write (Idempotency)

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:

{
  "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.
• Polling: GET /v1/jobs/{job_id}/candidates, then GET /v1/candidates/{candidate_id} and /scores.

Next steps

• Browse every endpoint in the API reference.
• Try the full flow end to end in the Sandbox.