Authentication & permissions

Every CVViZ API request requires a customer API credential. Credentials belong to one CVViZ account and cannot be used to access another account's data.

Create a credential

An authorized account administrator can manage credentials from Settings > Developers.

When creating a credential:

Give it a name that identifies the integration.
Grant only the scopes the integration needs.
Copy the generated secret immediately. It is displayed only once.
Store it in a server-side secret manager.

Create separate credentials for separate integrations. To rotate a credential, create a replacement, update the integration, confirm it works, and revoke the old credential.

Send the credential

Send the secret in the HTTPS Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_SECRET

Do not send credentials in URLs, query parameters, browser code, mobile applications, public repositories, logs, or support messages.

Scopes used by the published API

Scope	Grants access to
`jobs.read`	Read jobs and job pre-screening questions.
`jobs.write`	Create jobs, update approved core job fields and job tags, and manage the supported publication flags. Creation follows the account approval workflow.
`jobs.status.write`	Change supported lifecycle codes on existing jobs (see job options). Does not grant approval bypass, publication or deletion.
`candidates.read`	Read candidates, stages, tags, events, screening answers, benchmark resumes, and interview feedback.
`resumes.download`	Download original candidate resumes and explicitly request temporary direct file URLs, subject to content-access policy.
`candidates.profile.write`	Update approved candidate profile fields.
`candidates.write`	Add candidate tags and update a candidate application's stage.
`applications.read`	Read candidate and job associations.
`applications.write`	Add an existing candidate to an existing job.
`organization.read`	Read users, departments, hiring managers, grades, client companies, industries, job functions, employer types and job options.
`notes.read`	Read non-private candidate and job notes. Tasks use their separate task scopes.
`notes.write`	Add non-private plain candidate and job notes.
`documents.read`	Read candidate-document metadata. This scope does not return file URLs or download credentials.
`tasks.read`	Read non-private candidate, job, and unassociated tasks.
`tasks.write`	Create non-private tasks and update tasks created by the same API credential.
`offers.read`	Read candidate job-offer metadata. This scope does not return signed file URLs or internal delivery details.

A credential must have every scope required by the endpoint. The endpoint reference lists its required scope.

Adding scopes to CVViZ does not change existing credentials. Rotate a credential and explicitly select the additional scopes when an integration needs them.

jobs.write creates a job through the account's standard workflow: active when approval is disabled, or pending approval when it is enabled. jobs.status.write is separate because changing an existing job's lifecycle is a distinct operation. Publication is controlled by the supported publication fields under jobs.write and never bypasses approval or capacity checks.

candidates.read returns resume filenames and stable authenticated download links, but not file bytes or direct signed URLs. Downloading requires resumes.download. Requesting include=resume_download_url on candidate detail requires both scopes. General document uploads/downloads, resume imports and candidate creation remain unpublished.

Access requirements

Customer API availability is controlled by the account's CVViZ plan or an active API add-on. Only users with the appropriate account role can create, view, or revoke API credentials.

Authorization failures

401 Unauthorized: the credential is missing, malformed, expired, revoked, or invalid.
403 Forbidden: the credential is valid but lacks the required scope, or the account does not have active API access through its plan or API add-on.

Treat the secret like a password. If it may have been exposed, replace and revoke it immediately.

Was this helpful?

Still need help? Ask the team