1. Start here
CVViZ API Documentation
  • Start here
    • Quickstart
    • Authentication & permissions
  • Guides
    • API concepts
    • Create a job
    • Find candidates and download resumes
    • Pagination & filtering
    • Rate limits & usage
    • Errors & troubleshooting
    • Safe retries & idempotency
  • Jobs
    • Create a job
      POST
    • List jobs
      GET
    • Get a job
      GET
    • Update a job
      PATCH
    • List candidates for a job
      GET
    • List job benchmark resumes
      GET
    • List candidate job offers
      GET
    • Update a candidate application stage
      PATCH
    • Update job status
      PATCH
  • Candidates
    • List candidates
      GET
    • Get a candidate
      GET
    • Update a candidate
      PATCH
    • List applications for a candidate
      GET
    • List candidate events
      GET
    • List candidate documents
      GET
    • Download a candidate resume
      GET
  • Tasks
    • List tasks
    • Create a task
    • Update a task
    • Update task completion
  • Notes & tags
    • List job notes
    • Add a job note
    • List tags for a job
    • Add tags to a job
    • List tags for a candidate
    • Add tags to a candidate
    • List candidate notes
    • Add a candidate note
    • List candidate tags
  • Screening & interviews
    • List job pre-screening questions
    • List candidate screening answers
    • List candidate interview feedback
  • Organization & lookup data
    • List candidate stages for a job
    • Get job creation options
    • List industries
    • List job functions
    • List employer types
    • List client companies
    • List account users
    • List departments
    • List hiring managers
    • List candidate grades
  1. Start here

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:
1.
Give it a name that identifies the integration.
2.
Grant only the scopes the integration needs.
3.
Copy the generated secret immediately. It is displayed only once.
4.
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:
Do not send credentials in URLs, query parameters, browser code, mobile
applications, public repositories, logs, or support messages.

Available scopes#

ScopeGrants access to
jobs.readRead jobs and job pre-screening questions.
jobs.writeCreate jobs, update approved core job fields and job tags, and manage the supported publication flags. Creation follows the account approval workflow.
jobs.status.writeChange supported lifecycle codes on existing jobs (see job options). Does not grant approval bypass, publication or deletion.
candidates.readRead candidates, stages, tags, events, screening answers, benchmark resumes, and interview feedback.
resumes.downloadDownload original candidate resumes and explicitly request temporary direct file URLs, subject to content-access policy.
candidates.profile.writeUpdate approved candidate profile fields.
candidates.writeAdd candidate tags and update a candidate application's stage.
applications.readRead candidate and job associations.
applications.writeAdd an existing candidate to an existing job.
organization.readRead users, departments, hiring managers, grades, client companies, industries, job functions, employer types and job options.
notes.readRead non-private candidate and job notes. Private notes and tasks are excluded.
notes.writeAdd non-pprivate plain candidate and job notes.
documents.readRead candidate-document metadata. This scope does not return file URLs or download credentials.
tasks.readRead non-private candidate, job, and unassociated tasks.
tasks.writeCreate non-private tasks and update tasks created by the same API credential.
offers.readRead 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's plan does not grant customer API access.
Treat the secret like a password. If it may have been exposed, replace and
revoke it immediately.
Previous
Quickstart
Next
API concepts
Built with