{ "info": { "name": "TalentOS API", "description": "Full HTTP endpoint reference for the TalentOS recruitment platform.\n\n**Auth setup:**\n1. Mint a Bearer token at https://talentosglobal.co/account → API keys.\n2. Set the `apiToken` collection variable to that token (raw, including the `tk_` prefix).\n3. Set `baseUrl` to your environment (`https://talentosglobal.co` for prod).\n\nEvery protected endpoint inherits the collection-level Bearer auth.\nPublic endpoints (auth: \"public\") use `noauth` and ignore the token.\n\nGenerated from `app/api-docs/sections.ts` — re-run `scripts/generate-postman.ts` after endpoint changes.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "baseUrl", "value": "https://talentosglobal.co", "type": "string", "description": "Platform host. Use https://talentosglobal.co for production, or your tenant subdomain (https://acme.talentosglobal.co) for branded routing." }, { "key": "apiToken", "value": "", "type": "string", "description": "Bearer token raw value (starts with `tk_`). Mint at /account → API keys. Shown ONCE at creation — store it here." } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiToken}}", "type": "string" } ] }, "item": [ { "name": "Authentication", "description": "Two methods. Browser apps use cookie sessions (login sets a 14-day HttpOnly cookie). Programmatic clients use Bearer tokens — generate a key under /account → API keys, then send `Authorization: Bearer tk_…` with every request. Both methods resolve to the same tenant scoping + RBAC; any endpoint marked `session` or `session + role` also accepts a Bearer token of the appropriate role.", "item": [ { "name": "POST /api/auth/signup", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/signup", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "signup" ] }, "description": "Create a tenant + admin user, sign in. Also fires a verification email — the new admin lands signed-in but `emailVerified: false` until they click the link.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"companyName\": \"Acme Bank\",\n \"adminName\": \"Jane Doe\",\n \"adminEmail\": \"jane@acmebank.com\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/signup", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "signup" ] }, "description": "Create a tenant + admin user, sign in. Also fires a verification email — the new admin lands signed-in but `emailVerified: false` until they click the link.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"companyName\": \"Acme Bank\",\n \"adminName\": \"Jane Doe\",\n \"adminEmail\": \"jane@acmebank.com\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"tenant\": { \"id\": \"acme-bank\", \"name\": \"Acme Bank\" }, \"user\": { \"email\": \"\", \"emailVerified\": false, } }" } ] }, { "name": "POST /api/auth/verify-email", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/verify-email", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "verify-email" ] }, "description": "Consume a verification token. Idempotent: a second click returns `alreadyVerified: true` rather than 404. POST (not GET) so mail-client prefetchers can't accidentally consume the token.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"token\": \"<64-hex>\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/verify-email", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "verify-email" ] }, "description": "Consume a verification token. Idempotent: a second click returns `alreadyVerified: true` rather than 404. POST (not GET) so mail-client prefetchers can't accidentally consume the token.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"token\": \"<64-hex>\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"user\": { \"emailVerified\": true, } }" } ] }, { "name": "POST /api/auth/resend-verification", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/auth/resend-verification", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "resend-verification" ] }, "description": "Mint a fresh verification token + email it. Rate-limited to 3/min per email. Already-verified users get `alreadyVerified: true` instead of a new mail.\n\n**Auth:** `session`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/auth/resend-verification", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "resend-verification" ] }, "description": "Mint a fresh verification token + email it. Rate-limited to 3/min per email. Already-verified users get `alreadyVerified: true` instead of a new mail.\n\n**Auth:** `session`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"sent\": true\n}" } ] }, { "name": "POST /api/auth/login", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/login", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "login" ] }, "description": "Sign in. Sets session cookie.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"email\": \"jane@acmebank.com\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/login", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "login" ] }, "description": "Sign in. Sets session cookie.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"email\": \"jane@acmebank.com\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"user\": { ... } }" } ] }, { "name": "POST /api/auth/logout", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/auth/logout", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "logout" ] }, "description": "Destroy current session.\n\n**Auth:** `session`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/auth/logout", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "logout" ] }, "description": "Destroy current session.\n\n**Auth:** `session`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true\n}" } ] }, { "name": "GET /api/auth/me", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/auth/me", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "me" ] }, "description": "Resolve the current session to a user.\n\n**Auth:** `session`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/auth/me", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "me" ] }, "description": "Resolve the current session to a user.\n\n**Auth:** `session`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"user\": {\n \"email\": \"...\",\n \"name\": \"...\",\n \"role\": \"...\",\n \"tenantId\": \"...\"\n }\n}" } ] }, { "name": "POST /api/auth/forgot-password", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/forgot-password", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "forgot-password" ] }, "description": "Request a password-reset email.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"email\": \"jane@acmebank.com\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/forgot-password", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "forgot-password" ] }, "description": "Request a password-reset email.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"email\": \"jane@acmebank.com\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"dryRun\": false\n}" } ] }, { "name": "POST /api/auth/reset-password", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/reset-password", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "reset-password" ] }, "description": "Complete password reset using a one-time token.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"token\": \"<32-byte-hex>\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/reset-password", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "reset-password" ] }, "description": "Complete password reset using a one-time token.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"token\": \"<32-byte-hex>\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"user\": { ... } }" } ] }, { "name": "POST /api/auth/invite", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/invite", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "invite" ] }, "description": "Invite a teammate (admin/CHRO only).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "body": { "mode": "raw", "raw": "{\n \"email\": \"amara@acmebank.com\",\n \"name\": \"Amara D.\",\n \"role\": \"recruiter\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/invite", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "invite" ] }, "description": "Invite a teammate (admin/CHRO only).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "body": { "mode": "raw", "raw": "{\n \"email\": \"amara@acmebank.com\",\n \"name\": \"Amara D.\",\n \"role\": \"recruiter\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"invite\": {\n \"inviteUrl\": \"...\"\n }\n}" } ] }, { "name": "POST /api/auth/accept-invite", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/accept-invite", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "accept-invite" ] }, "description": "Set password on an invited account; signs the user in.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"token\": \"\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/auth/accept-invite", "host": [ "{{baseUrl}}" ], "path": [ "api", "auth", "accept-invite" ] }, "description": "Set password on an invited account; signs the user in.\n\n**Auth:** `public`\n**Reference:** [/api-docs#auth](https://talentosglobal.co/api-docs#auth)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"token\": \"\",\n \"password\": \"********\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"user\": { ... } }" } ] } ] }, { "name": "Tenants + Team", "description": "Self-tenant operations + team management. Every tenant is isolated; the API never returns cross-tenant data.", "item": [ { "name": "GET /api/tenants/me", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me" ] }, "description": "Get the caller's tenant record.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me" ] }, "description": "Get the caller's tenant record.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"tenant\": {\n \"id\": \"...\",\n \"name\": \"...\",\n \"plan\": \"pilot\",\n \"logoUrl\": \"...\",\n \"brandColor\": \"#7c3aed\",\n \"tagline\": \"...\"\n }\n}" } ] }, { "name": "PATCH /api/tenants/me", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/tenants/me", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me" ] }, "description": "Update branding (name, tagline, brandColor, logoUploadId, logoUrl) and monthly AI budget.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)", "body": { "mode": "raw", "raw": "{\n \"name\": \"Acme Bank\",\n \"tagline\": \"...\",\n \"brandColor\": \"#7c3aed\",\n \"monthlyBudgetUsd\": 50\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "GET /api/team", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/team", "host": [ "{{baseUrl}}" ], "path": [ "api", "team" ] }, "description": "List users in the caller's tenant (hashed passwords scrubbed).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)" }, "response": [] }, { "name": "GET /api/tenants/me/api-keys", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/api-keys", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "api-keys" ] }, "description": "List Bearer tokens issued for this tenant. Returns sanitised projections (prefix only — full token is only visible once at create time).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/api-keys", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "api-keys" ] }, "description": "List Bearer tokens issued for this tenant. Returns sanitised projections (prefix only — full token is only visible once at create time).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"keys\": [\n {\n \"id\": \"key_\",\n \"name\": \"Production sync\",\n \"tokenPrefix\": \"tk_a1b2c3d4\",\n \"role\": \"admin\",\n \"createdAt\": \"\",\n \"createdBy\": \"jane@acme.com\",\n \"lastUsedAt\": \"\",\n \"revoked\": false\n }\n ]\n}" } ] }, { "name": "POST /api/tenants/me/api-keys", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/api-keys", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "api-keys" ] }, "description": "Mint a new Bearer token. The raw token is returned ONCE — store it immediately; we keep only a scrypt hash. Role defaults to admin.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)", "body": { "mode": "raw", "raw": "{\n \"name\": \"Workday integration\",\n \"role\": \"recruiter\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/api-keys", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "api-keys" ] }, "description": "Mint a new Bearer token. The raw token is returned ONCE — store it immediately; we keep only a scrypt hash. Role defaults to admin.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)", "body": { "mode": "raw", "raw": "{\n \"name\": \"Workday integration\",\n \"role\": \"recruiter\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"key\": { \"id\": \"key_\", \"tokenPrefix\": \"tk_a1b2c3d4\", }, \"rawToken\": \"tk_<64-hex>\" }" } ] }, { "name": "DELETE /api/tenants/me/api-keys/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/api-keys/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "api-keys", ":id" ] }, "description": "Revoke a key. Soft-deletes (sets revoked=true) — the row is retained for the audit trail. Subsequent requests using that token return 401.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/api-keys/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "api-keys", ":id" ] }, "description": "Revoke a key. Soft-deletes (sets revoked=true) — the row is retained for the audit trail. Subsequent requests using that token return 401.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#tenants](https://talentosglobal.co/api-docs#tenants)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true\n}" } ] } ] }, { "name": "Vacancies", "description": "Job postings. Public read for open status only — used by the careers portal. Admin/recruiter writes only.", "item": [ { "name": "GET /api/vacancies", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/vacancies", "host": [ "{{baseUrl}}" ], "path": [ "api", "vacancies" ] }, "description": "List the caller's tenant vacancies (filters: q, status, subsidiaryId).\n\n**Auth:** `session`\n**Reference:** [/api-docs#vacancies](https://talentosglobal.co/api-docs#vacancies)" }, "response": [] }, { "name": "POST /api/vacancies", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/vacancies", "host": [ "{{baseUrl}}" ], "path": [ "api", "vacancies" ] }, "description": "Create a new vacancy.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#vacancies](https://talentosglobal.co/api-docs#vacancies)", "body": { "mode": "raw", "raw": "{\n \"title\": \"Senior Backend Engineer\",\n \"description\": \"...\",\n \"location\": \"Lagos\",\n \"level\": \"senior\",\n \"employmentType\": \"full_time\",\n \"skills\": [\n \"Go\",\n \"Postgres\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "GET /api/vacancies/[id]", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/vacancies/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "vacancies", ":id" ] }, "description": "Get a vacancy (cross-tenant id returns 404).\n\n**Auth:** `session`\n**Reference:** [/api-docs#vacancies](https://talentosglobal.co/api-docs#vacancies)" }, "response": [] }, { "name": "PATCH /api/vacancies/[id]", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/vacancies/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "vacancies", ":id" ] }, "description": "Update mutable fields.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#vacancies](https://talentosglobal.co/api-docs#vacancies)" }, "response": [] }, { "name": "DELETE /api/vacancies/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/vacancies/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "vacancies", ":id" ] }, "description": "Delete a vacancy.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#vacancies](https://talentosglobal.co/api-docs#vacancies)" }, "response": [] }, { "name": "GET /api/careers/vacancies", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/careers/vacancies", "host": [ "{{baseUrl}}" ], "path": [ "api", "careers", "vacancies" ] }, "description": "PUBLIC list of all open vacancies across all tenants. Sanitized projection. Pagination via limit + offset.\n\n**Auth:** `public`\n**Reference:** [/api-docs#vacancies](https://talentosglobal.co/api-docs#vacancies)", "auth": { "type": "noauth" } }, "response": [] }, { "name": "GET /api/careers/vacancies/[id]", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/careers/vacancies/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "careers", "vacancies", ":id" ] }, "description": "PUBLIC vacancy read. Open-status only. Stripped of internal fields.\n\n**Auth:** `public`\n**Reference:** [/api-docs#vacancies](https://talentosglobal.co/api-docs#vacancies)", "auth": { "type": "noauth" } }, "response": [] } ] }, { "name": "Candidates", "description": "Applicants linked to vacancies. Public apply endpoint for the careers portal; tenant-scoped CRUD for recruiters.", "item": [ { "name": "POST /api/careers/apply", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/careers/apply", "host": [ "{{baseUrl}}" ], "path": [ "api", "careers", "apply" ] }, "description": "PUBLIC application submit. Dedupes by (email, vacancyId). Increments vacancy.applicants.\n\n**Auth:** `public`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"vacancyId\": \"vac_...\",\n \"name\": \"Kwame M.\",\n \"email\": \"kwame@...\",\n \"experience\": 7,\n \"skills\": [\n \"Go\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/careers/apply", "host": [ "{{baseUrl}}" ], "path": [ "api", "careers", "apply" ] }, "description": "PUBLIC application submit. Dedupes by (email, vacancyId). Increments vacancy.applicants.\n\n**Auth:** `public`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)", "auth": { "type": "noauth" }, "body": { "mode": "raw", "raw": "{\n \"vacancyId\": \"vac_...\",\n \"name\": \"Kwame M.\",\n \"email\": \"kwame@...\",\n \"experience\": 7,\n \"skills\": [\n \"Go\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"candidate\": {\n \"id\": \"cand_...\",\n \"dedup\": false\n }\n}" } ] }, { "name": "GET /api/candidates", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/candidates", "host": [ "{{baseUrl}}" ], "path": [ "api", "candidates" ] }, "description": "List tenant candidates (filters: jobId, stage, q).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)" }, "response": [] }, { "name": "GET /api/candidates/[id]", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/candidates/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "candidates", ":id" ] }, "description": "Get a candidate.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)" }, "response": [] }, { "name": "PATCH /api/candidates/[id]", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/candidates/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "candidates", ":id" ] }, "description": "Update candidate; common use is stage transitions. Hiring transitions auto-bump vacancy.hired.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)", "body": { "mode": "raw", "raw": "{\n \"stage\": \"interview\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "DELETE /api/candidates/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/candidates/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "candidates", ":id" ] }, "description": "Delete a candidate.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)" }, "response": [] }, { "name": "POST /api/candidates/import", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/candidates/import", "host": [ "{{baseUrl}}" ], "path": [ "api", "candidates", "import" ] }, "description": "Bulk import up to 500 rows. Per-row error reporting. Dedup by (email, vacancyId).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)", "body": { "mode": "raw", "raw": "{\n \"rows\": [\n {\n \"name\": \"...\",\n \"email\": \"...\",\n \"vacancyId\": \"...\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/candidates/import", "host": [ "{{baseUrl}}" ], "path": [ "api", "candidates", "import" ] }, "description": "Bulk import up to 500 rows. Per-row error reporting. Dedup by (email, vacancyId).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#candidates](https://talentosglobal.co/api-docs#candidates)", "body": { "mode": "raw", "raw": "{\n \"rows\": [\n {\n \"name\": \"...\",\n \"email\": \"...\",\n \"vacancyId\": \"...\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"total\": 100, \"created\": 87, \"updated\": 8, \"skipped\": 5, \"errors\": [ ... ] }" } ] } ] }, { "name": "Offers", "description": "Formal offer letters extended to candidates at the offer pipeline stage. Accepting an offer auto-bumps the candidate to `hired` and increments the vacancy's hired counter. Status transitions fire `offer.sent`, `offer.accepted`, `offer.declined` webhooks.", "item": [ { "name": "GET /api/offers", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/offers", "host": [ "{{baseUrl}}" ], "path": [ "api", "offers" ] }, "description": "List offers in your tenant. Filters: candidateId, vacancyId, status.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#offers](https://talentosglobal.co/api-docs#offers)" }, "response": [] }, { "name": "POST /api/offers", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/offers", "host": [ "{{baseUrl}}" ], "path": [ "api", "offers" ] }, "description": "Create an offer. Candidate + vacancy must belong to your tenant. Setting status=\"sent\" stamps `sentAt` and fires `offer.sent`.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#offers](https://talentosglobal.co/api-docs#offers)", "body": { "mode": "raw", "raw": "{\n \"candidateId\": \"cand_...\",\n \"vacancyId\": \"vac_...\",\n \"baseSalary\": 80000,\n \"currency\": \"USD\",\n \"bonus\": 10000,\n \"signOnBonus\": 5000,\n \"startDate\": \"2026-06-01\",\n \"status\": \"draft\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/offers", "host": [ "{{baseUrl}}" ], "path": [ "api", "offers" ] }, "description": "Create an offer. Candidate + vacancy must belong to your tenant. Setting status=\"sent\" stamps `sentAt` and fires `offer.sent`.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#offers](https://talentosglobal.co/api-docs#offers)", "body": { "mode": "raw", "raw": "{\n \"candidateId\": \"cand_...\",\n \"vacancyId\": \"vac_...\",\n \"baseSalary\": 80000,\n \"currency\": \"USD\",\n \"bonus\": 10000,\n \"signOnBonus\": 5000,\n \"startDate\": \"2026-06-01\",\n \"status\": \"draft\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"offer\": { \"id\": \"ofr_...\", \"status\": \"draft\", ... } }" } ] }, { "name": "GET /api/offers/[id]", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/offers/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "offers", ":id" ] }, "description": "Single-offer detail. Cross-tenant id → 404.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#offers](https://talentosglobal.co/api-docs#offers)" }, "response": [] }, { "name": "PATCH /api/offers/[id]", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/offers/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "offers", ":id" ] }, "description": "Update mutable fields + transition status. `accepted` triggers candidate stage = hired + vacancy.hired++.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#offers](https://talentosglobal.co/api-docs#offers)", "body": { "mode": "raw", "raw": "{\n \"status\": \"accepted\",\n \"decision\": \"Candidate accepted via Slack\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "DELETE /api/offers/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/offers/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "offers", ":id" ] }, "description": "Delete an offer.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`\n**Reference:** [/api-docs#offers](https://talentosglobal.co/api-docs#offers)" }, "response": [] } ] }, { "name": "Interviews", "description": "Scheduled interviews tied to a candidate + vacancy + panel. Scorecards are recorded inline on the interview record. `interview.scheduled` and `interview.completed` webhooks fire on the corresponding transitions.", "item": [ { "name": "GET /api/interviews", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/interviews", "host": [ "{{baseUrl}}" ], "path": [ "api", "interviews" ] }, "description": "List interviews. Filters: candidateId, vacancyId, status, from, to (ISO datetimes).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#interviews](https://talentosglobal.co/api-docs#interviews)" }, "response": [] }, { "name": "POST /api/interviews", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/interviews", "host": [ "{{baseUrl}}" ], "path": [ "api", "interviews" ] }, "description": "Schedule an interview. Kind: phone | video | onsite | technical | panel. Fires `interview.scheduled`.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#interviews](https://talentosglobal.co/api-docs#interviews)", "body": { "mode": "raw", "raw": "{\n \"candidateId\": \"cand_...\",\n \"vacancyId\": \"vac_...\",\n \"scheduledAt\": \"2026-06-01T14:00:00Z\",\n \"durationMin\": 45,\n \"kind\": \"video\",\n \"locationOrUrl\": \"https://meet.example.com/x\",\n \"interviewers\": [\n \"Jane Doe\",\n \"John Smith\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/interviews", "host": [ "{{baseUrl}}" ], "path": [ "api", "interviews" ] }, "description": "Schedule an interview. Kind: phone | video | onsite | technical | panel. Fires `interview.scheduled`.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#interviews](https://talentosglobal.co/api-docs#interviews)", "body": { "mode": "raw", "raw": "{\n \"candidateId\": \"cand_...\",\n \"vacancyId\": \"vac_...\",\n \"scheduledAt\": \"2026-06-01T14:00:00Z\",\n \"durationMin\": 45,\n \"kind\": \"video\",\n \"locationOrUrl\": \"https://meet.example.com/x\",\n \"interviewers\": [\n \"Jane Doe\",\n \"John Smith\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"interview\": { \"id\": \"iv_...\", \"status\": \"scheduled\", ... } }" } ] }, { "name": "PATCH /api/interviews/[id]", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/interviews/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "interviews", ":id" ] }, "description": "Update fields, transition status, or upsert a scorecard. Pass `addScorecard: { interviewer, score, recommendation, notes? }` to record post-interview feedback. `status=completed` fires `interview.completed` webhook.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#interviews](https://talentosglobal.co/api-docs#interviews)", "body": { "mode": "raw", "raw": "{\n \"status\": \"completed\",\n \"addScorecard\": {\n \"interviewer\": \"Jane Doe\",\n \"score\": 87,\n \"recommendation\": \"strong_hire\",\n \"notes\": \"Excellent system design.\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "DELETE /api/interviews/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/interviews/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "interviews", ":id" ] }, "description": "Delete an interview.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`\n**Reference:** [/api-docs#interviews](https://talentosglobal.co/api-docs#interviews)" }, "response": [] } ] }, { "name": "Subsidiaries / Agencies / Integrations", "description": "Organisational structure + external partners + connected systems. All three share the same shape — tenant-scoped list/create + per-id get/patch/delete.", "item": [ { "name": "GET /api/subsidiaries", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/subsidiaries", "host": [ "{{baseUrl}}" ], "path": [ "api", "subsidiaries" ] }, "description": "List + POST create. Detail at /api/subsidiaries/[id] (GET/PATCH/DELETE).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#subsidiaries](https://talentosglobal.co/api-docs#subsidiaries)" }, "response": [] }, { "name": "GET /api/agencies", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/agencies", "host": [ "{{baseUrl}}" ], "path": [ "api", "agencies" ] }, "description": "List + POST create. Detail at /api/agencies/[id] (GET/PATCH/DELETE).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`\n**Reference:** [/api-docs#subsidiaries](https://talentosglobal.co/api-docs#subsidiaries)" }, "response": [] }, { "name": "GET /api/integrations", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/integrations", "host": [ "{{baseUrl}}" ], "path": [ "api", "integrations" ] }, "description": "List + POST create. Detail at /api/integrations/[id] (GET/PATCH/DELETE). Provider slug must be lowercase alphanumeric + hyphens.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#subsidiaries](https://talentosglobal.co/api-docs#subsidiaries)" }, "response": [] } ] }, { "name": "AI tools", "description": "Claude-powered features. Each call tracks tokens + cost per tenant and shows up on /spend. Pass entity ids OR inline payloads — server fetches authoritative data when ids are supplied.", "item": [ { "name": "POST /api/ai/chat", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/chat", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "chat" ] }, "description": "Conversational AI Recruiter (streaming).\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)", "body": { "mode": "raw", "raw": "{ \"messages\": [...], \"stream\": true, \"language\": \"en\" }", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "POST /api/ai/screen", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/screen", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "screen" ] }, "description": "Score a candidate against a job.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/screen", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "screen" ] }, "description": "Score a candidate against a job.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"result\": { \"matchScore\": 87, \"verdict\": \"strong_match\", \"strengths\": [...], \"concerns\": [...], \"recommendation\": \"...\" } }" } ] }, { "name": "POST /api/ai/outreach", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/outreach", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "outreach" ] }, "description": "Draft personalised candidate outreach.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)", "body": { "mode": "raw", "raw": "{\n \"candidateId\": \"cand_...\",\n \"vacancyId\": \"vac_...\",\n \"tone\": \"warm\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/outreach", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "outreach" ] }, "description": "Draft personalised candidate outreach.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)", "body": { "mode": "raw", "raw": "{\n \"candidateId\": \"cand_...\",\n \"vacancyId\": \"vac_...\",\n \"tone\": \"warm\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"result\": {\n \"subject\": \"...\",\n \"body\": \"...\",\n \"follow_up_body\": \"...\"\n }\n}" } ] }, { "name": "POST /api/ai/draft-offer", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/draft-offer", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "draft-offer" ] }, "description": "Draft an offer letter.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)", "body": { "mode": "raw", "raw": "{\n \"candidateId\": \"cand_...\",\n \"vacancyId\": \"vac_...\",\n \"baseSalary\": 12000,\n \"currency\": \"USD\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "POST /api/ai/interview-questions", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/interview-questions", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "interview-questions" ] }, "description": "Generate technical / behavioral / scenario interview questions for a role.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/interview-questions", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "interview-questions" ] }, "description": "Generate technical / behavioral / scenario interview questions for a role.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"result\": { \"technical\": [...], \"behavioral\": [...], \"scenario\": [...], \"red_flag_signals\": [...] } }" } ] }, { "name": "POST /api/ai/source-candidates", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/ai/source-candidates", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "source-candidates" ] }, "description": "Find best matches from the tenant talent pool given a brief.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)", "body": { "mode": "raw", "raw": "{\n \"brief\": \"Looking for a senior fintech eng with...\",\n \"count\": 5\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "POST /api/ai/generate-jd", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/ai/generate-jd", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "generate-jd" ] }, "description": "Generate a job description from a brief.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "response": [] }, { "name": "POST /api/ai/salary-benchmark", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/ai/salary-benchmark", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "salary-benchmark" ] }, "description": "Benchmark compensation for a role + location.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "response": [] }, { "name": "POST /api/ai/transcript-summary", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/ai/transcript-summary", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "transcript-summary" ] }, "description": "Analyse an interview transcript.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "response": [] }, { "name": "POST /api/ai/attrition-risk", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/ai/attrition-risk", "host": [ "{{baseUrl}}" ], "path": [ "api", "ai", "attrition-risk" ] }, "description": "Score attrition risk for an employee.\n\n**Auth:** `session`\n**Reference:** [/api-docs#ai](https://talentosglobal.co/api-docs#ai)" }, "response": [] } ] }, { "name": "Library", "description": "Saved artifacts from AI calls (JDs, screens, offers, etc.). Append-only with tenant scoping.", "item": [ { "name": "GET /api/library", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/library", "host": [ "{{baseUrl}}" ], "path": [ "api", "library" ] }, "description": "List items (filters: kind, q).\n\n**Auth:** `session`\n**Reference:** [/api-docs#library](https://talentosglobal.co/api-docs#library)" }, "response": [] }, { "name": "POST /api/library", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/library", "host": [ "{{baseUrl}}" ], "path": [ "api", "library" ] }, "description": "Save an item.\n\n**Auth:** `session`\n**Reference:** [/api-docs#library](https://talentosglobal.co/api-docs#library)", "body": { "mode": "raw", "raw": "{ \"kind\": \"jd\", \"title\": \"Senior Backend JD\", \"payload\": {...}, \"source\": \"claude\" }", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "GET /api/library/[id]", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/library/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "library", ":id" ] }, "description": "Get an item.\n\n**Auth:** `session`\n**Reference:** [/api-docs#library](https://talentosglobal.co/api-docs#library)" }, "response": [] }, { "name": "DELETE /api/library/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/library/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "library", ":id" ] }, "description": "Delete an item.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `hiring_manager`, `recruiter`, `agency_admin`\n**Reference:** [/api-docs#library](https://talentosglobal.co/api-docs#library)" }, "response": [] } ] }, { "name": "Uploads", "description": "File storage. Bytes go to Vercel Blob in production (durable, CDN-fronted) or local FS in dev. Metadata in KV.", "item": [ { "name": "POST /api/upload", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/upload", "host": [ "{{baseUrl}}" ], "path": [ "api", "upload" ] }, "description": "Multipart upload. Accepts PDF/DOC/DOCX/TXT/RTF/ODT/JPG/PNG/WebP. 8 MB max.\n\n**Auth:** `session`\n**Reference:** [/api-docs#uploads](https://talentosglobal.co/api-docs#uploads)" }, "response": [] }, { "name": "GET /api/upload/[id]", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/upload/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "upload", ":id" ] }, "description": "Read bytes. Redirects to Blob CDN URL when active.\n\n**Auth:** `session`\n**Reference:** [/api-docs#uploads](https://talentosglobal.co/api-docs#uploads)" }, "response": [] }, { "name": "DELETE /api/upload/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/upload/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "upload", ":id" ] }, "description": "Delete bytes + metadata. Uploader or admin only.\n\n**Auth:** `session`\n**Reference:** [/api-docs#uploads](https://talentosglobal.co/api-docs#uploads)" }, "response": [] } ] }, { "name": "Audit + Analytics", "description": "Tamper-evident audit trail + executive analytics. Append-only LIST (LPUSH on KV). Tenant-scoped.", "item": [ { "name": "GET /api/audit", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/audit", "host": [ "{{baseUrl}}" ], "path": [ "api", "audit" ] }, "description": "List audit events (filters: type, since, q, limit).\n\n**Auth:** `session`\n**Reference:** [/api-docs#audit](https://talentosglobal.co/api-docs#audit)" }, "response": [] }, { "name": "POST /api/audit", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/audit", "host": [ "{{baseUrl}}" ], "path": [ "api", "audit" ] }, "description": "Record an arbitrary audit event from the client.\n\n**Auth:** `session`\n**Reference:** [/api-docs#audit](https://talentosglobal.co/api-docs#audit)" }, "response": [] }, { "name": "GET /api/audit/export", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/audit/export", "host": [ "{{baseUrl}}" ], "path": [ "api", "audit", "export" ] }, "description": "Download tenant audit trail as CSV (17 columns).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#audit](https://talentosglobal.co/api-docs#audit)" }, "response": [] }, { "name": "GET /api/audit/spend", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/audit/spend", "host": [ "{{baseUrl}}" ], "path": [ "api", "audit", "spend" ] }, "description": "AI spend aggregation (window: 24h, 7d, 30d, all).\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`\n**Reference:** [/api-docs#audit](https://talentosglobal.co/api-docs#audit)" }, "response": [] }, { "name": "GET /api/insights", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/insights", "host": [ "{{baseUrl}}" ], "path": [ "api", "insights" ] }, "description": "Executive dashboard data. Vacancies + candidates + audit + AI cost aggregated for /reports.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`, `recruiter`, `hiring_manager`, `interviewer`\n**Reference:** [/api-docs#audit](https://talentosglobal.co/api-docs#audit)" }, "response": [] } ] }, { "name": "Account / NDPR + GDPR", "description": "Data-subject rights endpoints. Admin self-serves export + tenant delete; no support ticket required.", "item": [ { "name": "GET /api/account/export", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/account/export", "host": [ "{{baseUrl}}" ], "path": [ "api", "account", "export" ] }, "description": "Download tenant-scoped JSON: users + library + uploads + vacancies + candidates + audit. Hashed passwords + tokens scrubbed.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#account](https://talentosglobal.co/api-docs#account)" }, "response": [] }, { "name": "POST /api/account/delete", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/account/delete", "host": [ "{{baseUrl}}" ], "path": [ "api", "account", "delete" ] }, "description": "Cascade-delete tenant + all owned data. Requires typed confirmation matching tenant id. Clears session cookie on success.\n\n**Auth:** `session+role`\n**Roles:** `admin`\n**Reference:** [/api-docs#account](https://talentosglobal.co/api-docs#account)", "body": { "mode": "raw", "raw": "{\n \"confirm\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Webhooks", "description": "Outbound HTTP push. Subscribe an HTTPS endpoint to one or more events; we POST a signed JSON envelope when they happen. Pairs with API keys (pull) to give you a complete integration surface. Every delivery includes an `X-TalentOS-Signature: t=,v1=` header where `hex = HMAC-SHA256(t + \".\" + raw_body, secret)`. Verify the signature on every request — and reject any payload more than 5 minutes old to defeat replay. Available events: `candidate.applied`, `candidate.stage_changed`, `vacancy.published`, `offer.sent`, `offer.accepted`, `offer.declined`, `interview.scheduled`, `interview.completed`. Delivery is durable: failed deliveries enter a retry queue with exponential backoff (30s → 2m → 10m → 1h → 6h) and the subscription auto-disables after 20 consecutive failures.", "item": [ { "name": "GET /api/tenants/me/webhooks", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "webhooks" ] }, "description": "List webhook subscriptions for this tenant. Secrets are NOT returned — they're shown ONCE at create time.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#webhooks](https://talentosglobal.co/api-docs#webhooks)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "webhooks" ] }, "description": "List webhook subscriptions for this tenant. Secrets are NOT returned — they're shown ONCE at create time.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#webhooks](https://talentosglobal.co/api-docs#webhooks)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"webhooks\": [\n {\n \"id\": \"wh_\",\n \"url\": \"https://\",\n \"events\": [\n \"candidate.applied\"\n ],\n \"enabled\": true,\n \"createdAt\": \"\",\n \"lastDeliveryAt\": \"\",\n \"lastStatus\": \"200\"\n }\n ],\n \"availableEvents\": [\n \"candidate.applied\",\n \"candidate.stage_changed\",\n \"vacancy.published\"\n ]\n}" } ] }, { "name": "POST /api/tenants/me/webhooks", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "webhooks" ] }, "description": "Register a new subscription. URL must be HTTPS. Response returns the full record INCLUDING `secret` — store it on your end; we don't show it again.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#webhooks](https://talentosglobal.co/api-docs#webhooks)", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://your-system.example.com/talentos-hook\",\n \"events\": [\n \"candidate.applied\",\n \"vacancy.published\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "webhooks" ] }, "description": "Register a new subscription. URL must be HTTPS. Response returns the full record INCLUDING `secret` — store it on your end; we don't show it again.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#webhooks](https://talentosglobal.co/api-docs#webhooks)", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://your-system.example.com/talentos-hook\",\n \"events\": [\n \"candidate.applied\",\n \"vacancy.published\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{ \"ok\": true, \"webhook\": { \"id\": \"wh_\", \"url\": \"\", \"events\": [...], \"secret\": \"whsec_<64-hex>\", \"enabled\": true, } }" } ] }, { "name": "DELETE /api/tenants/me/webhooks/[id]", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/webhooks/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "webhooks", ":id" ] }, "description": "Delete a subscription. Hard-delete — secret is unrecoverable, so retention has no value.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#webhooks](https://talentosglobal.co/api-docs#webhooks)" }, "response": [ { "name": "200 OK — documented response", "originalRequest": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{apiToken}}", "description": "Bearer token minted at /account → API keys. Cookie-session callers (browsers) don't need this header — the collection assumes server-to-server use." } ], "url": { "raw": "{{baseUrl}}/api/tenants/me/webhooks/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "tenants", "me", "webhooks", ":id" ] }, "description": "Delete a subscription. Hard-delete — secret is unrecoverable, so retention has no value.\n\n**Auth:** `session+role`\n**Roles:** `admin`, `chro`\n**Reference:** [/api-docs#webhooks](https://talentosglobal.co/api-docs#webhooks)" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true\n}" } ] } ] }, { "name": "Health + Status", "description": "Operational endpoints. Public; safe to expose to monitors + uptime tools.", "item": [ { "name": "GET /api/health", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/health", "host": [ "{{baseUrl}}" ], "path": [ "api", "health" ] }, "description": "Platform health. Storage backend + probe, AI live state, integration posture (Blob, Resend, Sentry), audit stats. Polled by /status page.\n\n**Auth:** `public`\n**Reference:** [/api-docs#ops](https://talentosglobal.co/api-docs#ops)", "auth": { "type": "noauth" } }, "response": [] } ] } ] }