Tasks

Use the tasks endpoints to read, create, and update to-do items for your team. A task has a title, optional notes and due date, an optional assigned agent, and can be linked to one company, contact, or sale.

List tasks

GET /api/v2/organizations/{organization_id}/tasks

This endpoint supports limit and cursor. Tasks are returned newest first.

Key response fields:

Name
task_id
Description
The task identifier used for the task detail endpoint.
Name
title
Description
Short description of the task.
Name
notes
Description
Longer notes for the task, when present.
Name
due_at
Description
When the task is due, when set.
Name
completed_at
Description
When the task was completed. null while the task is open.
Name
agent_id
Description
The assigned agent, when the task is assigned.
Name
company_id
Description
The linked company, when the task is linked to a company.
Name
contact_id
Description
The linked contact, when the task is linked to a contact.
Name
sale_id
Description
The linked sale, when the task is linked to a sale.
Name
created_at
Description
When the task was created.

List tasks

curl -G https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/tasks \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25"

Example response

{
  "data": [
    {
      "task_id": "HR_id_example_task_id",
      "title": "Send onboarding docs",
      "notes": "Use the new template",
      "due_at": "2026-07-15T17:00:00Z",
      "completed_at": null,
      "agent_id": "HR_id_example_agent_id",
      "company_id": "HR_id_example_company_id",
      "contact_id": null,
      "sale_id": null,
      "created_at": "2026-07-09T12:00:00Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": null,
    "has_more": false
  }
}

Create a task

POST /api/v2/organizations/{organization_id}/tasks

Use this endpoint to create one task under an organization. title is required. A task can be linked to at most one of company_id, contact_id, or sale_id.

Request body fields:

Name
title
Description
Required short description of the task.
Name
notes
Description
Optional longer notes for the task.
Name
due_at
Description
Optional due timestamp in ISO 8601 format, for example 2026-07-15T17:00:00Z.
Name
agent_id
Description
Optional agent to assign the task to. Must belong to the same organization.
Name
company_id
Description
Optional company to link the task to.
Name
contact_id
Description
Optional contact to link the task to.
Name
sale_id
Description
Optional sale to link the task to.

Create one task

curl -X POST https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/tasks \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Send onboarding docs",
    "notes": "Use the new template",
    "due_at": "2026-07-15T17:00:00Z",
    "agent_id": "HR_id_example_agent_id",
    "company_id": "HR_id_example_company_id"
  }'

Example response

{
  "task_id": "HR_id_example_task_id",
  "title": "Send onboarding docs",
  "notes": "Use the new template",
  "due_at": "2026-07-15T17:00:00Z",
  "completed_at": null,
  "agent_id": "HR_id_example_agent_id",
  "company_id": "HR_id_example_company_id",
  "contact_id": null,
  "sale_id": null,
  "created_at": "2026-07-09T12:00:00Z"
}

Get a task

GET /api/v2/organizations/{organization_id}/tasks/{task_id}

Use the task_id returned by the list endpoint.

This endpoint returns one task in the same canonical task shape used by the list endpoint.

Get one task

curl https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/tasks/HR_id_example_task_id \
  -H "X-API-KEY: your-api-key"

Example response

{
  "task_id": "HR_id_example_task_id",
  "title": "Call back the walk-in lead",
  "notes": null,
  "due_at": null,
  "completed_at": null,
  "agent_id": null,
  "company_id": null,
  "contact_id": null,
  "sale_id": null,
  "created_at": "2026-07-09T12:00:00Z"
}

Update a task

PATCH /api/v2/organizations/{organization_id}/tasks/{task_id}

Use this endpoint to update one task. Omitted fields are left unchanged. Set nullable fields to null to clear them. Set completed_at to a timestamp to complete a task, or null to reopen it.

A task can be linked to at most one of company_id, contact_id, or sale_id after the update.

Update one task

curl -X PATCH https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/tasks/HR_id_example_task_id \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Send onboarding docs",
    "completed_at": "2026-07-10T16:30:00Z",
    "company_id": null,
    "sale_id": "HR_id_example_sale_id"
  }'

Example response

{
  "task_id": "HR_id_example_task_id",
  "title": "Send onboarding docs",
  "notes": null,
  "due_at": null,
  "completed_at": "2026-07-10T16:30:00Z",
  "agent_id": null,
  "company_id": null,
  "contact_id": null,
  "sale_id": "HR_id_example_sale_id",
  "created_at": "2026-07-09T12:00:00Z"
}