Tasks

Create a task

Create a non-private task.

POST

/tasks

Create a task

curl --request POST \
  --url https://api.cvviz.com/v1/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: cvviz-integration-operation-001' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assignedTo": 18,
  "dueDate": "2026-11-01T10:00:00.000Z",
  "entityId": 501,
  "entityType": "candidate",
  "note": "Follow up with the candidate."
}
'

{
  "data": {
    "assignedTo": 18,
    "assignedToName": "Recruiter name",
    "createdAt": "2026-10-11T10:00:00.000Z",
    "dueDate": "2026-11-01T10:00:00.000Z",
    "entityId": 501,
    "entityType": "candidate",
    "id": 7301,
    "isCompleted": false,
    "note": "Follow up with the candidate.",
    "updatedAt": null
  }
}

Set entityType to candidate or job and supply entityId to associate the task. For an unassociated task, omit both fields.

assignedTo is an active user ID from GET /users.

Permissions

tasks.write

Safe retries

Send an Idempotency-Key. Retry the same request with the same key to avoid repeating the write. See Safe retries & idempotency.

Authorizations

Authorizationstringheaderrequired

Use Authorization: Bearer <api-credential>.

Headers

Idempotency-Keystringheaderrequired

Unique key for this write: 8-128 letters, digits, periods, underscores, colons or hyphens. Reusing the same key with the same request replays its original result; different content returns 409.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]{8,128}$

Example: cvviz-integration-operation-001

Body

assignedTointeger | null

Active user ID from GET /users. Send null to leave the task unassigned.

Required range: 1 <= x

Example: 18

dueDatestring | null

entityIdinteger

Required when entityType is candidate or job. Use an ID from your account; omit for an unassociated task.

Required range: 1 <= x

Example: 501

entityTypeenum<string>default:none

Optional association. Defaults to none; candidate and job require entityId.

Available options: none, candidate, job

notestringrequired

Required string length: 1 - 5000

Example: Follow up with the candidate.

Response

Mutation applied or safely replayed.

X-API-Daily-Limitintegerheader

Daily account request allowance, when metered. Shared across API credentials.

Required range: 0 <= x

X-API-Daily-Remainingintegerheader

Requests remaining in the daily window after admission.

Required range: 0 <= x

X-API-Daily-Resetstringheader

Daily window reset time in UTC.

X-API-Monthly-Limitintegerheader

Monthly account request allowance, when metered. Shared across API credentials.

Required range: 0 <= x

X-API-Monthly-Remainingintegerheader

Requests remaining in the monthly window after admission.

Required range: 0 <= x

X-API-Monthly-Resetstringheader

Monthly window reset time in UTC.

X-Request-IDstringheader

Request correlation identifier.

X-API-Contractstringheader

Response envelope contract version.

Example: canonical-v1

RateLimit-Limitintegerheader

Example: 600

RateLimit-Remainingintegerheader

Example: 598

RateLimit-Resetintegerheader

Example: 30

dataobjectrequired

Show child attributes

Still need help? Ask the team