Blucollarz API

Machine-readable spec: /api/openapi.json

Authentication

Every /api/v1/* route and the MCP endpoint require a secret.

Authorization: Bearer blz_live_...
# or
X-API-Key: blz_live_...

Create keys in Admin → Settings → API Keys. Keys are stored in Mongo (ApiKeys) — only a hash is saved; copy the secret when it is shown once.

REST — Candidate (by user id)

Method	Path	Description
GET	`/api/v1/candidates/:userId/gate-status`	Profile complete, KYC verified, has selected role
GET	`/api/v1/candidates/:userId/progress`	Applications, interviews, medical, stats

REST — Candidate (by phone, WhatsApp)

Pass the inbound WhatsApp number as phone. Accepts 9876543210, 919876543210, or +919876543210. Optional countryCode when sending national digits only.

Method	Path	Description
GET	`/api/v1/candidates/by-phone/lookup?phone=…`	Resolve `userId` from phone
GET	`/api/v1/candidates/by-phone/gate-status?phone=…`	Gate status without knowing user id
GET	`/api/v1/candidates/by-phone/progress?phone=…`	Full pipeline progress by phone

MCP

Streamable HTTP endpoint: /api/mcp

resolve_candidate_by_phone — WhatsApp phone → userId
get_candidate_gate_status — userId or phone
get_candidate_progress — userId or phone

{
  "mcpServers": {
    "blucollarz": {
      "url": "https://your-api.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer blz_live_YOUR_KEY"
      }
    }
  }
}

Example

# WhatsApp flow — phone only
curl -s \
  -H "Authorization: Bearer $BLUCOLLARZ_API_KEY" \
  "http://localhost:3003/api/v1/candidates/by-phone/progress?phone=919876543210"

# Or resolve userId first
curl -s \
  -H "Authorization: Bearer $BLUCOLLARZ_API_KEY" \
  "http://localhost:3003/api/v1/candidates/by-phone/lookup?phone=919876543210"