Tasks

A task is an action item: one line saying what needs doing, an optional due date, and the users or groups responsible for it. A task can be attached to the record it concerns, such as a contact, a deal, or an email thread, and can belong to a milestone. Use this resource to create, assign, and complete tasks, and to list the tasks for a record or a due window.

A task is visible to your key when your key’s user owns it or is assigned to it, directly or through a group, or when the task has no owner. Anyone who can see a task can edit it.

Your team creates tasks directly. Carom’s agents also propose tasks from email and meetings as proposals; accepting one creates the task.

#The task object

Returned by every task endpoint. The nested thread, contact, organization, milestone, file, calendar_event, and deal objects are previews of linked records. Each appears only when the task links to that record and the record is visible to your key; otherwise only the bare id is set.

Attributes

  • idstring · uuid

    Unique identifier for the task.

  • assignmentstring · nullable

    What needs doing, in one line. This is the task’s title.

  • descriptionstring · nullable

    Longer notes about the task.

  • assigned_user_idsarray of strings · uuid · nullable

    Users responsible for the task. See users.

  • assigned_group_idsarray of strings · uuid · nullable

    Groups responsible for the task. Every member of an assigned group can see it.

  • user_idstring · uuid · nullable

    The user who owns the task. Null for a task with no owner, which everyone in the account can see.

  • duestring · date · nullable

    The day the task is due.

  • completed_atstring · date-time · nullable

    When the task was completed. Null while the task is open.

  • milestone_idstring · uuid · nullable

    The milestone the task belongs to.

  • contact_idstring · uuid · nullable

    The contact the task concerns.

  • organization_idstring · uuid · nullable

    The organization the task concerns.

  • deal_idstring · uuid · nullable

    The deal the task concerns.

  • thread_idstring · uuid · nullable

    The email thread the task came from or concerns.

  • file_idstring · uuid · nullable

    The file the task concerns.

  • calendar_event_idstring · uuid · nullable

    The meeting the task concerns.

  • space_idstring · uuid · nullable

    The space the task was added to directly.

  • ai_generatedboolean · nullable

    True when the task was created by accepting an agent’s proposal.

  • ai_generation_justificationstring · nullable

    The evidence the agent quoted when it proposed the task.

  • ai_completedboolean · nullable

    True when an agent marked the task complete.

  • ai_completion_justificationstring · nullable

    The agent’s reason for marking the task complete.

  • created_atstring · date-time
  • updated_atstring · date-time
  • threadobject

    Preview of the linked thread.

    Show 6 child attributesHide child attributes
    • idstring · uuid
    • subjectstring · nullable
    • snippetstring · nullable
    • has_attachmentsboolean · nullable
    • first_sent_atstring · date-time · nullable
    • last_sent_atstring · date-time · nullable
  • contactobject

    Preview of the linked contact, with an id and name.

  • organizationobject

    Preview of the linked organization, with an id and name.

  • milestoneobject

    Preview of the milestone. Present only when the milestone is visible to your key.

    Show 4 child attributesHide child attributes
    • idstring · uuid
    • namestring · nullable
    • descriptionstring · nullable
    • duestring · date · nullable
  • fileobject

    Preview of the linked file.

    Show 4 child attributesHide child attributes
    • idstring · uuid
    • namestring · nullable
    • file_namestring · nullable
    • extensionstring · nullable
  • calendar_eventobject

    Preview of the linked meeting.

    Show 4 child attributesHide child attributes
    • idstring · uuid
    • namestring · nullable
    • start_datetimestring · date-time · nullable

      When a timed event starts. Null for an all-day event.

    • all_day_start_datestring · date · nullable

      The first day of an all-day event. Null for a timed event.

  • dealobject

    Preview of the linked deal.

    Show 3 child attributesHide child attributes
    • idstring · uuid
    • namestring
    • statusstring
      openwonlost
The task object 
{
  "id": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01",
  "assignment": "Send the Q4 renewal proposal",
  "description": "Priya asked for pricing on all 14 properties, with the new maintenance tier broken out.",
  "assigned_user_ids": ["9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e"],
  "assigned_group_ids": [],
  "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
  "due": "2026-09-12",
  "completed_at": null,
  "milestone_id": "f3bb9a33-6078-4fbc-9166-a28e5cc0dce7",
  "contact_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
  "organization_id": null,
  "deal_id": null,
  "thread_id": "7548f9d5-2a32-4ed3-8c14-aac4ebe980a2",
  "file_id": null,
  "calendar_event_id": null,
  "space_id": null,
  "ai_generated": true,
  "ai_generation_justification": "\"Could you send over the renewal numbers before the 15th?\"",
  "ai_completed": false,
  "ai_completion_justification": null,
  "created_at": "2026-09-03T18:52:30.715Z",
  "updated_at": "2026-09-03T18:52:30.715Z",
  "thread": {
    "id": "7548f9d5-2a32-4ed3-8c14-aac4ebe980a2",
    "subject": "Renewal for 2027",
    "snippet": "Could you send over the renewal numbers before the 15th? I'm out the week after.",
    "has_attachments": false,
    "first_sent_at": "2026-09-02T15:10:04.167Z",
    "last_sent_at": "2026-09-03T17:41:22.518Z"
  },
  "contact": {
    "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
    "name": "Priya Natarajan"
  },
  "milestone": {
    "id": "f3bb9a33-6078-4fbc-9166-a28e5cc0dce7",
    "name": "Wildgrove renewal",
    "description": "Signed 2027 contract by the end of September.",
    "due": "2026-09-30"
  }
}
get/tasks Read key

#List tasks

Returns the open tasks visible to your key, 25 per page by default, soonest due first. Tasks with no due date come last. Filter by a linked record, by assignee, by due window, or by a search query, and page through the result with a cursor in either direction.

Query parameters

  • querystring

    Match against assignment and description. Up to 500 characters.

  • completedbooleandefault false

    false returns open tasks; true returns completed tasks instead.

  • slicestring

    Restrict to tasks linked to one kind of record, or to a due window. Due windows use your key’s user’s time zone; weeks end on Sunday. later means no due date or due after next week.

    contactsorganizationsemailsfilesoverduetodaytomorrowthis_weeknext_weeklater
  • assigned_user_idsstring or array of strings · uuid

    Tasks assigned to any of these users. Pass one id, or repeat the parameter as assigned_user_ids[]. At most 50.

  • contact_idstring · uuid

    Tasks attached to this contact.

  • organization_idstring · uuid

    Tasks attached to this organization.

  • deal_idstring · uuid

    Tasks attached to this deal.

  • calendar_event_idstring · uuid

    Tasks attached to this meeting.

  • space_idstring · uuid

    Tasks in this space: tasks added to it directly, tasks carrying one of its tags, and tasks attached to its contacts or organizations.

  • limitintegerdefault 25

    Tasks per page, from 1 to 100. Values outside that range are clamped.

  • next_cursorstring

    Opaque token from the previous page’s page_info.next_cursor. Omit to start from the beginning. See Pagination.

  • prev_cursorstring

    Opaque token from page_info.prev_cursor, to fetch the page before this one. See Pagination.

Returns

  • collectionobject

    A page of tasks and the cursors around it.

    Show 4 child attributesHide child attributes
    • recordsarray of tasks

      Up to limit tasks in due order.

    • page_infopage info

      Where this page sits in the full list. Pass next_cursor back to fetch the next page while has_more_after is true.

    • slice_keystring · nullable

      The slice that was applied.

    • filtersobject · nullable

      The filters that were applied, echoed back. Always includes completed.

Errors

  • 400invalid_cursorThe cursor is unreadable, or came from another list or sort.
  • 400invalid_requestA parameter is malformed, for example an id that isn’t a UUID or more than 50 assignee ids.
  • 404record_not_foundA contact_id, organization_id, deal_id, calendar_event_id, or space_id doesn’t match a record visible to your key.
get/tasks 
curl "https://api.carom.io/tasks?contact_id=1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41&limit=2" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "collection": {
    "slice_key": null,
    "filters": {
      "completed": false,
      "contact_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41"
    },
    "page_info": {
      "limit": 2,
      "has_more_before": false,
      "has_more_after": true,
      "prev_cursor": null,
      "next_cursor": "q7Rm2XkV9pLc4TnW8aHs"
    },
    "records": [
      {
        "id": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01",
        "assignment": "Send the Q4 renewal proposal",
        "due": "2026-09-12",
        "completed_at": null,
        …
      },
      {
        "id": "0361c1d0-a72d-43bc-86c1-26537f0236ec",
        "assignment": "Confirm headcount for the 2027 contract",
        "due": "2026-09-18",
        "completed_at": null,
        …
      }
    ]
  }
}
post/tasks Write key

#Create a task

Creates a task owned by your key’s user. Assign it to users or groups, give it a due date, and attach it to the records it concerns. Assignees other than your key’s user receive a notification.

Every record id you send must be a record visible to your key, or the request fails with invalid_request and nothing is created. Assignee ids outside your account are dropped; assigned_user_ids and assigned_group_ids in the response show which were kept.

Request body application/json

  • taskobjectrequired
    Show 15 child attributesHide child attributes
    • assignmentstringrequired

      What needs doing, in one line.

    • descriptionstring
    • assigned_user_idsarray of strings · uuid
    • assigned_group_idsarray of strings · uuid
    • duestring · date

      As YYYY-MM-DD.

    • due_shortcutstring

      Set due relative to the current date in your key’s user’s time zone: this_week is the coming Sunday and next_week the Sunday after. Any value except date overrides due; date uses due as sent. Any other value is rejected with invalid_request.

      todaytomorrowthis_weeknext_weekdate
    • completed_atstring · date-time

      Record a task that is already done.

    • milestone_idstring · uuid

      The milestone to add the task to.

    • contact_idstring · uuid
    • organization_idstring · uuid
    • deal_idstring · uuid
    • thread_idstring · uuid
    • file_idstring · uuid
    • calendar_event_idstring · uuid
    • space_idstring · uuid

Returns

The new task object, wrapped in task, with status 201.

Errors

  • 400missing_paramsassignment is missing.
  • 400invalid_requestA field failed validation, or a record id isn’t a record visible to your key. error.fields says which.
post/tasks 
curl https://api.carom.io/tasks \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "assignment": "Book the site walk at the Alder Street property",
      "due": "2026-09-25",
      "assigned_user_ids": ["44c3f6da-393b-4664-9bfa-3c14e76b8cb8"],
      "contact_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
      "milestone_id": "f3bb9a33-6078-4fbc-9166-a28e5cc0dce7"
    }
  }'
Response201 
{
  "task": {
    "id": "ffffb36c-42a3-41c2-8962-5577814a9a62",
    "assignment": "Book the site walk at the Alder Street property",
    "assigned_user_ids": ["44c3f6da-393b-4664-9bfa-3c14e76b8cb8"],
    "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "due": "2026-09-25",
    "completed_at": null,
    "contact_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
    "milestone_id": "f3bb9a33-6078-4fbc-9166-a28e5cc0dce7",
    "ai_generated": false,
    …
  }
}
get/tasks/{id} Read key

#Retrieve a task

Returns a single task, open or completed, with previews of the records it links to.

Path parameters

  • idstring · uuidrequired

    The task’s id.

Returns

The task object, wrapped in task.

Errors

  • 404record_not_foundNo task with that id is visible to your key.
get/tasks/{id} 
curl https://api.carom.io/tasks/e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01 \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "task": {
    "id": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01",
    "assignment": "Send the Q4 renewal proposal",
    "due": "2026-09-12",
    "completed_at": null,
    …
    "contact": {
      "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
      "name": "Priya Natarajan"
    }
  }
}
patch/tasks/{id} Write key

#Update a task

Changes the fields you send and leaves the rest alone. To complete a task, send completed_at. To reopen it, send "completed_at": null or "incomplete": true. Omitting both leaves the completion state as it is. Users and groups newly added to the assignee lists receive a notification.

Path parameters

  • idstring · uuidrequired

Request body application/json

  • taskobjectrequired

    Any of the attributes accepted by Create a task, none of them required. Send a record id as null to detach the task from that record. A new record id must be a record visible to your key; resending the id the task already links to is accepted even when your key can’t see that record. One more field is accepted.

    Show 1 child attributeHide child attributes
    • incompleteboolean

      true reopens the task. Not stored. Sending it with a non-null completed_at is rejected as contradictory.

Returns

The updated task object, wrapped in task.

Errors

  • 400invalid_requestA field failed validation, a new record id isn’t a record visible to your key, or incomplete: true came with a non-null completed_at. Nothing is changed.
  • 404record_not_foundNo task with that id is visible to your key.
patch/tasks/{id} 
curl -X PATCH https://api.carom.io/tasks/e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01 \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "completed_at": "2026-09-11T16:20:00Z"
    }
  }'
Response200 
{
  "task": {
    "id": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01",
    "assignment": "Send the Q4 renewal proposal",
    "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "due": "2026-09-12",
    "completed_at": "2026-09-11T16:20:00.000Z",
    "updated_at": "2026-09-11T16:20:03.902Z",
    …
  }
}
delete/tasks/{id} Write key

#Delete a task

Permanently deletes a task. Anyone who can see a task can delete it. Pending agent proposals about the task, such as one to mark it complete, expire.

Path parameters

  • idstring · uuidrequired

Returns

An empty response with status 204.

Errors

  • 404record_not_foundNo task with that id is visible to your key.
delete/tasks/{id} 
curl -X DELETE https://api.carom.io/tasks/e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a01 \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response204 
No content
get/tasks/count Read key

#Count tasks

Counts the tasks that List tasks would return for the same filters, without fetching them. The count is always exact, so exact is always true and capped always false.

Query parameters

  • query, completed, slice, assigned_user_ids, contact_id, organization_id, deal_id, calendar_event_id, space_id

    As on List tasks.

Returns

  • countcount

    The number of matching tasks is in total.

Errors

  • 400invalid_requestA parameter is malformed, as on List tasks.
  • 404record_not_foundA record filter doesn’t match a record visible to your key.
get/tasks/count 
curl "https://api.carom.io/tasks/count?slice=overdue" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "count": {
    "total": 6,
    "exact": true,
    "capped": false,
    "cap": null
  }
}