openapi: 3.1.0
info:
description: 'Fixture''s public v1 CRM API for Accounts, Contacts, Deals, Leads, Activities, Pipelines, Notes, and Tasks. Authenticate with `Authorization: Bearer ...` using either a Fixture API key or a Fixture OAuth access token.'
title: Fixture Accounts Tasks API
version: v1
servers:
- url: https://beta-api.fixture.app
security:
- bearerAuth: []
tags:
- description: Create, read, update, and delete Tasks.
name: Tasks
paths:
/api/v1/tasks:
get:
deprecated: false
description: Return a paginated list of Tasks. Filter by `task_status_id`, `assignee_id`, and `entity_type` + `entity_id` together (to scope to one CRM record), plus `due_before`/`due_after` and created/updated timestamp windows. Pass `overdue=true` to limit results to Tasks past their due date and not in a completed status. Sort supports `created_at` or `-created_at`; pagination uses `limit` and `cursor`.
operationId: listTasks
parameters:
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Maximum number of records to return.
in: query
name: limit
required: false
schema:
default: 50
example: 50
type: integer
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Opaque cursor returned by the previous page. Omit for the first page.
in: query
name: cursor
required: false
schema:
example: eyJ2IjoxLCJzb3J0IjoiLWNyZWF0ZWRfYXQiLCJ2YWx1ZSI6IjIwMjYtMDMtMjJUMTQ6MDA6MDFaIiwiaWQiOiI2NjAxZDYxZC0xMTI5LTQyN2MtODI1NS0wOGI1ZjEyZGRhYjUifQ
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Sort by a supported field. Prefix with `-` for descending order.
in: query
name: sort
required: false
schema:
default: -created_at
example: -created_at
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Opaque Task status ID with the `taskstatus_` prefix.
in: query
name: task_status_id
required: false
schema:
example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Opaque user ID with the `user_` prefix.
in: query
name: assignee_id
required: false
schema:
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Filter to a specific related entity type.
in: query
name: entity_type
required: false
schema:
enum:
- account
- contact
- deal
- lead
example: contact
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Filter to one specific related entity. Requires `entity_type`.
in: query
name: entity_id
required: false
schema:
example: contact_6M4jXRFuLpTQ3nM4PkGvW8
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Return only Tasks due on or before this ISO 8601 date.
in: query
name: due_before
required: false
schema:
example: '2026-04-30'
format: date
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Return only Tasks due on or after this ISO 8601 date.
in: query
name: due_after
required: false
schema:
example: '2026-04-01'
format: date
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Return only records created after this ISO 8601 timestamp.
in: query
name: created_after
required: false
schema:
example: '2026-03-01T00:00:00Z'
format: date-time
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Return only records created before this ISO 8601 timestamp.
in: query
name: created_before
required: false
schema:
example: '2026-03-31T23:59:59Z'
format: date-time
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Return only records updated after this ISO 8601 timestamp.
in: query
name: updated_after
required: false
schema:
example: '2026-03-01T00:00:00Z'
format: date-time
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: Return only records updated before this ISO 8601 timestamp.
in: query
name: updated_before
required: false
schema:
example: '2026-03-31T23:59:59Z'
format: date-time
type: string
- allowEmptyValue: false
allowReserved: false
deprecated: false
description: When true, return only Tasks past their due date and not in a done status.
in: query
name: overdue
required: false
schema:
default: false
example: true
type: boolean
responses:
'200':
content:
application/json:
example:
data:
- assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
completed_at: null
created_at: '2026-04-19T09:00:00Z'
created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
description: Confirm the renewal timeline after the quarterly review.
due_date: '2026-04-30'
entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
entity_type: contact
id: task_8W3jXRFuLpTQ3nM4PkGvW0
task_status:
category: todo
color: gray
id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
name: To Do
position: 0
task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
title: Follow up with Acme
updated_at: '2026-04-19T09:00:00Z'
pagination:
has_more: false
limit: 50
next_cursor: null
schema:
$ref: '#/components/schemas/V1TaskListPayload'
description: Paginated Task list.
'400':
content:
application/json:
example:
error:
code: invalid_parameter
message: entity_type and entity_id must be provided together
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Invalid filter, pagination, or sort parameter.
'401':
content:
application/json:
example:
error:
code: unauthorized
message: Invalid or missing API key
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Missing or invalid API key.
'403':
content:
application/json:
example:
error:
code: forbidden
message: 'Missing required scope: tasks:read'
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: API key is missing the required scope.
security:
- bearerAuth: []
summary: List Tasks
tags:
- Tasks
post:
deprecated: false
description: Create a new Task. Resolve the Task status by passing exactly one of `task_status_id` (a `taskstatus_` ID) or `task_status_name` (looked up case-insensitively among the organization's Task Statuses). To link the Task to a CRM record, pass `entity_type` and `entity_id` together.
operationId: createTask
requestBody:
content:
application/json:
example:
assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
description: Confirm the renewal timeline after the quarterly review.
due_date: '2026-04-30'
entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
entity_type: contact
task_status_name: To Do
title: Follow up with Acme
schema:
$ref: '#/components/schemas/V1CreateTaskRequest'
required: true
responses:
'201':
content:
application/json:
example:
data:
assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
completed_at: null
created_at: '2026-04-19T09:00:00Z'
created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
description: Confirm the renewal timeline after the quarterly review.
due_date: '2026-04-30'
entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
entity_type: contact
id: task_8W3jXRFuLpTQ3nM4PkGvW0
task_status:
category: todo
color: gray
id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
name: To Do
position: 0
task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
title: Follow up with Acme
updated_at: '2026-04-19T09:00:00Z'
schema:
$ref: '#/components/schemas/V1TaskDetailResponsePayload'
description: Task created.
'400':
content:
application/json:
example:
error:
code: validation_error
message: 'Task status not found: VIP'
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Validation error — includes missing required fields, blank optional strings, unknown references (e.g. a task_status_name with no match or a cross-org task_status_id), mutually-exclusive status inputs, and mismatched entity_type/entity_id pairs.
'401':
content:
application/json:
example:
error:
code: unauthorized
message: Invalid or missing API key
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Missing or invalid API key.
'403':
content:
application/json:
example:
error:
code: forbidden
message: 'Missing required scope: tasks:write'
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: API key is missing the required scope.
security:
- bearerAuth: []
summary: Create a Task
tags:
- Tasks
/api/v1/tasks/{task_id}:
delete:
deprecated: false
description: Delete a Task by ID.
operationId: deleteTask
parameters:
- deprecated: false
description: Opaque Task ID with the `task_` prefix.
in: path
name: task_id
required: true
schema:
example: task_8W3jXRFuLpTQ3nM4PkGvW0
type: string
responses:
'200':
content:
application/json:
example:
deleted: true
id: task_8W3jXRFuLpTQ3nM4PkGvW0
schema:
$ref: '#/components/schemas/V1TaskDeletePayload'
description: Task deleted.
'400':
content:
application/json:
example:
error:
code: invalid_parameter
message: Invalid Task ID
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Invalid Task ID.
'401':
content:
application/json:
example:
error:
code: unauthorized
message: Invalid or missing API key
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Missing or invalid API key.
'403':
content:
application/json:
example:
error:
code: forbidden
message: 'Missing required scope: tasks:write'
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: API key is missing the required scope.
'404':
content:
application/json:
example:
error:
code: not_found
message: Task not found
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Task not found.
security:
- bearerAuth: []
summary: Delete a Task
tags:
- Tasks
get:
deprecated: false
description: Return a single Task by its `task_` ID with full detail, including the assignee, linked entity (when set), and resolved Task status.
operationId: getTask
parameters:
- deprecated: false
description: Opaque Task ID with the `task_` prefix.
in: path
name: task_id
required: true
schema:
example: task_8W3jXRFuLpTQ3nM4PkGvW0
type: string
responses:
'200':
content:
application/json:
example:
data:
assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
completed_at: null
created_at: '2026-04-19T09:00:00Z'
created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
description: Confirm the renewal timeline after the quarterly review.
due_date: '2026-04-30'
entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
entity_type: contact
id: task_8W3jXRFuLpTQ3nM4PkGvW0
task_status:
category: todo
color: gray
id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
name: To Do
position: 0
task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
title: Follow up with Acme
updated_at: '2026-04-19T09:00:00Z'
schema:
$ref: '#/components/schemas/V1TaskDetailResponsePayload'
description: Task detail.
'400':
content:
application/json:
example:
error:
code: invalid_parameter
message: Invalid Task ID
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Invalid Task ID.
'401':
content:
application/json:
example:
error:
code: unauthorized
message: Invalid or missing API key
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Missing or invalid API key.
'403':
content:
application/json:
example:
error:
code: forbidden
message: 'Missing required scope: tasks:read'
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: API key is missing the required scope.
'404':
content:
application/json:
example:
error:
code: not_found
message: Task not found
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Task not found.
security:
- bearerAuth: []
summary: Get a Task
tags:
- Tasks
patch:
deprecated: false
description: Partially update a Task by ID. `title`, `task_status_id`, and `task_status_name` are non-nullable — they cannot be cleared. When changing the status, pass either `task_status_id` or `task_status_name`, not both.
operationId: updateTask
parameters:
- deprecated: false
description: Opaque Task ID with the `task_` prefix.
in: path
name: task_id
required: true
schema:
example: task_8W3jXRFuLpTQ3nM4PkGvW0
type: string
requestBody:
content:
application/json:
example:
due_date: '2026-05-07'
task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
title: Follow up with Acme — v2
schema:
$ref: '#/components/schemas/V1UpdateTaskRequest'
required: true
responses:
'200':
content:
application/json:
example:
data:
assignee_id: user_9T5jXRFuLpTQ3nM4PkGvW2
completed_at: null
created_at: '2026-04-19T09:00:00Z'
created_by_id: user_9T5jXRFuLpTQ3nM4PkGvW2
description: Confirm the renewal timeline after the quarterly review.
due_date: '2026-04-30'
entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
entity_type: contact
id: task_8W3jXRFuLpTQ3nM4PkGvW0
task_status:
category: todo
color: gray
id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
name: To Do
position: 0
task_status_id: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
title: Follow up with Acme
updated_at: '2026-04-19T09:00:00Z'
schema:
$ref: '#/components/schemas/V1TaskDetailResponsePayload'
description: Updated Task.
'400':
content:
application/json:
example:
error:
code: validation_error
message: Task status not found in this organization
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Invalid ID or request body.
'401':
content:
application/json:
example:
error:
code: unauthorized
message: Invalid or missing API key
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Missing or invalid API key.
'403':
content:
application/json:
example:
error:
code: forbidden
message: 'Missing required scope: tasks:write'
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: API key is missing the required scope.
'404':
content:
application/json:
example:
error:
code: not_found
message: Task not found
schema:
$ref: '#/components/schemas/V1ErrorResponse'
description: Task not found.
security:
- bearerAuth: []
summary: Update a Task
tags:
- Tasks
components:
schemas:
V1UpdateTaskRequest:
description: Request body for partially updating a Task. Explicit JSON `null` on `description`, `assignee_id`, `due_date`, or the entity link clears the field; omitting the field leaves it untouched; empty strings are rejected. `task_status_id` and `task_status_name` are mutually exclusive on a single request.
properties:
assignee_id:
description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
oneOf:
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: string
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: 'null'
description:
oneOf:
- type: string
- type: 'null'
due_date:
example: '2026-04-30'
oneOf:
- example: '2026-04-30'
format: date
type: string
- example: '2026-04-30'
type: 'null'
entity_id:
oneOf:
- type: string
- type: 'null'
entity_type:
enum:
- account
- contact
- deal
- lead
oneOf:
- enum:
- account
- contact
- deal
- lead
type: string
- enum:
- account
- contact
- deal
- lead
type: 'null'
task_status_id:
type: string
task_status_name:
type: string
title:
type: string
required: []
title: V1UpdateTaskRequest
type: object
V1TaskPayload:
description: Task payload (shared by list and detail responses).
properties:
assignee_id:
description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
oneOf:
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: string
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: 'null'
completed_at:
oneOf:
- format: date-time
type: string
- type: 'null'
created_at:
example: '2026-03-22T14:00:01Z'
format: date-time
type: string
created_by_id:
description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
oneOf:
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: string
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: 'null'
description:
oneOf:
- type: string
- type: 'null'
due_date:
example: '2026-04-30'
oneOf:
- example: '2026-04-30'
format: date
type: string
- example: '2026-04-30'
type: 'null'
entity_id:
oneOf:
- type: string
- type: 'null'
entity_type:
enum:
- account
- contact
- deal
- lead
oneOf:
- enum:
- account
- contact
- deal
- lead
type: string
- enum:
- account
- contact
- deal
- lead
type: 'null'
id:
description: Opaque `task_` identifier.
example: task_8W3jXRFuLpTQ3nM4PkGvW0
type: string
task_status:
$ref: '#/components/schemas/V1TaskStatusPayload'
task_status_id:
description: Opaque `taskstatus_` identifier.
example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
type: string
title:
type: string
updated_at:
example: '2026-03-22T14:00:01Z'
format: date-time
type: string
required:
- assignee_id
- completed_at
- created_at
- created_by_id
- description
- due_date
- entity_id
- entity_type
- id
- task_status
- task_status_id
- title
- updated_at
title: V1TaskPayload
type: object
V1PaginationPayload:
description: Cursor pagination block for public list responses.
properties:
has_more:
description: Whether another page is available.
example: false
type: boolean
limit:
description: Requested page size.
example: 50
type: integer
next_cursor:
description: Opaque cursor to pass as `cursor` for the next page, or null when this is the last page.
example: null
type:
- string
- 'null'
required:
- limit
- next_cursor
- has_more
type: object
V1CreateTaskRequest:
description: Request body for creating a Task. `description` is plain text only; sending it clears any rich-text state the UI may have previously stored.
properties:
assignee_id:
description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
oneOf:
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: string
- description: Opaque `user_` identifier.
example: user_9T5jXRFuLpTQ3nM4PkGvW2
type: 'null'
description:
oneOf:
- type: string
- type: 'null'
due_date:
example: '2026-04-30'
oneOf:
- example: '2026-04-30'
format: date
type: string
- example: '2026-04-30'
type: 'null'
entity_id:
oneOf:
- type: string
- type: 'null'
entity_type:
enum:
- account
- contact
- deal
- lead
oneOf:
- enum:
- account
- contact
- deal
- lead
type: string
- enum:
- account
- contact
- deal
- lead
type: 'null'
task_status_id:
description: Opaque `taskstatus_` identifier.
example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
oneOf:
- description: Opaque `taskstatus_` identifier.
example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
type: string
- description: Opaque `taskstatus_` identifier.
example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
type: 'null'
task_status_name:
oneOf:
- type: string
- type: 'null'
title:
type: string
required:
- title
title: V1CreateTaskRequest
type: object
V1TaskListPayload:
description: Paginated list response for Tasks.
properties:
data:
items:
$ref: '#/components/schemas/V1TaskPayload'
type: array
pagination:
$ref: '#/components/schemas/V1PaginationPayload'
required:
- data
- pagination
title: V1TaskListPayload
type: object
V1ErrorResponse:
description: Standard error envelope for all public v1 API errors.
properties:
error:
properties:
code:
description: Stable machine-readable error code.
example: not_found
type: string
message:
description: Human-readable error message.
example: Account not found
type: string
required:
- code
- message
type: object
required:
- error
type: object
V1TaskStatusPayload:
description: Task status definition payload.
properties:
category:
type: string
color:
type: string
id:
description: Opaque `taskstatus_` identifier.
example: taskstatus_9Y4jXRFuLpTQ3nM4PkGvW1
type: string
name:
type: string
position:
type: integer
required:
- category
- color
- id
- name
- position
title: V1TaskStatusPayload
type: object
V1TaskDeletePayload:
description: Envelope returned when a Task is deleted.
properties:
deleted:
const: true
type: boolean
id:
description: Opaque `task_` identifier.
example: task_8W3jXRFuLpTQ3nM4PkGvW0
type: string
required:
- deleted
- id
title: V1TaskDeletePayload
type: object
V1TaskDetailResponsePayload:
description: Single-Task response envelope.
properties:
data:
$ref: '#/components/schemas/V1TaskPayload'
required:
- data
title: V1TaskDetailResponsePayload
type: object
securitySchemes:
bearerAuth:
bearerFormat: API key or OAuth access token
description: Send either a Fixture API key or a Fixture OAuth access token in the Authorization header as a bearer token.
scheme: bearer
type: http