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 Activities API
  version: v1
servers:
- url: https://beta-api.fixture.app
security:
- bearerAuth: []
tags:
- description: List and ingest CRM Activity records.
  name: Activities
paths:
  /api/v1/activities:
    get:
      deprecated: false
      description: Return a paginated list of Activities across all CRM entities. Pass `entity_type` and `entity_id` together to scope results to one Account, Contact, Deal, or Lead. Also supports filtering by `event_type` and `occurred_after`/`occurred_before` windows. Sort supports `occurred_at` or `-occurred_at`; pagination uses `limit` and `cursor`.
      operationId: listActivities
      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: -occurred_at
          example: -occurred_at
          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: Filter Activities by event type.
        in: query
        name: event_type
        required: false
        schema:
          example: custom
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only Activities that occurred after this ISO 8601 timestamp.
        in: query
        name: occurred_after
        required: false
        schema:
          example: '2026-03-01T00:00:00Z'
          format: date-time
          type: string
      - allowEmptyValue: false
        allowReserved: false
        deprecated: false
        description: Return only Activities that occurred before this ISO 8601 timestamp.
        in: query
        name: occurred_before
        required: false
        schema:
          example: '2026-03-31T23:59:59Z'
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - actor: null
                  content: Payment of $4,200 received for Q1 subscription.
                  created_at: '2026-03-22T14:00:01Z'
                  entities:
                  - entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                    entity_type: contact
                    role: primary
                  - entity_id: account_7B5jXRFuLpTQ3nM4PkGvW2
                    entity_type: account
                    role: related
                  external_id: invoice-1042
                  id: activity_3Q8jXRFuLpTQ3nM4PkGvW5
                  occurred_at: '2026-03-22T14:00:00Z'
                  title: 'Invoice #1042 paid'
                  type: billing.invoice_paid
                  updated_at: '2026-03-22T14:00:01Z'
                pagination:
                  has_more: false
                  limit: 50
                  next_cursor: null
              schema:
                $ref: '#/components/schemas/V1ActivityListPayload'
          description: Paginated Activity list.
        '400':
          content:
            application/json:
              example:
                error:
                  code: invalid_parameter
                  message: entity_id requires entity_type to be set
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Invalid filter or pagination 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: activities:read'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
      security:
      - bearerAuth: []
      summary: List Activities
      tags:
      - Activities
    post:
      deprecated: false
      description: 'Ingest a custom Activity attached to one or more CRM records (Contact, Account, or Deal — at least one is required). Pass `external_id` as an idempotency key: replays with the same `external_id` and identical fields return `200` with the existing Activity, while replays with different fields return `409 idempotency_conflict`.'
      operationId: createActivity
      requestBody:
        content:
          application/json:
            example:
              account_id: account_7B5jXRFuLpTQ3nM4PkGvW2
              body: Payment of $4,200 received for Q1 subscription.
              contact_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
              external_id: invoice-1042
              occurred_at: '2026-03-22T14:00:00Z'
              title: 'Invoice #1042 paid'
              type: billing.invoice_paid
            schema:
              $ref: '#/components/schemas/V1CreateActivityRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  actor: null
                  content: Payment of $4,200 received for Q1 subscription.
                  created_at: '2026-03-22T14:00:01Z'
                  entities:
                  - entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                    entity_type: contact
                    role: primary
                  - entity_id: account_7B5jXRFuLpTQ3nM4PkGvW2
                    entity_type: account
                    role: related
                  external_id: invoice-1042
                  id: activity_3Q8jXRFuLpTQ3nM4PkGvW5
                  occurred_at: '2026-03-22T14:00:00Z'
                  title: 'Invoice #1042 paid'
                  type: billing.invoice_paid
                  updated_at: '2026-03-22T14:00:01Z'
              schema:
                $ref: '#/components/schemas/V1ActivityDetailResponsePayload'
          description: Existing Activity returned for an idempotent replay.
        '201':
          content:
            application/json:
              example:
                data:
                  actor: null
                  content: Payment of $4,200 received for Q1 subscription.
                  created_at: '2026-03-22T14:00:01Z'
                  entities:
                  - entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                    entity_type: contact
                    role: primary
                  - entity_id: account_7B5jXRFuLpTQ3nM4PkGvW2
                    entity_type: account
                    role: related
                  external_id: invoice-1042
                  id: activity_3Q8jXRFuLpTQ3nM4PkGvW5
                  occurred_at: '2026-03-22T14:00:00Z'
                  title: 'Invoice #1042 paid'
                  type: billing.invoice_paid
                  updated_at: '2026-03-22T14:00:01Z'
              schema:
                $ref: '#/components/schemas/V1ActivityDetailResponsePayload'
          description: Activity created.
        '400':
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: At least one of contact_id, account_id, or deal_id is required
              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: activities:write'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
        '404':
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Contact not found
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Referenced entity not found.
        '409':
          content:
            application/json:
              example:
                error:
                  code: idempotency_conflict
                  message: Activity with external_id already exists with different fields
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Idempotency key reused with different request fields.
      security:
      - bearerAuth: []
      summary: Create a custom Activity
      tags:
      - Activities
  /api/v1/activities/{activity_id}:
    get:
      deprecated: false
      description: Return a single Activity by its `act_` ID with full detail, including linked entities and any replies.
      operationId: getActivity
      parameters:
      - deprecated: false
        description: Opaque Activity ID with the `activity_` prefix.
        in: path
        name: activity_id
        required: true
        schema:
          example: activity_3Q8jXRFuLpTQ3nM4PkGvW5
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  actor: null
                  content: Payment of $4,200 received for Q1 subscription.
                  created_at: '2026-03-22T14:00:01Z'
                  entities:
                  - entity_id: contact_6M4jXRFuLpTQ3nM4PkGvW8
                    entity_type: contact
                    role: primary
                  - entity_id: account_7B5jXRFuLpTQ3nM4PkGvW2
                    entity_type: account
                    role: related
                  external_id: invoice-1042
                  id: activity_3Q8jXRFuLpTQ3nM4PkGvW5
                  occurred_at: '2026-03-22T14:00:00Z'
                  title: 'Invoice #1042 paid'
                  type: billing.invoice_paid
                  updated_at: '2026-03-22T14:00:01Z'
              schema:
                $ref: '#/components/schemas/V1ActivityDetailResponsePayload'
          description: Activity detail.
        '400':
          content:
            application/json:
              example:
                error:
                  code: invalid_parameter
                  message: Invalid Activity ID
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Invalid Activity 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: activities:read'
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: API key is missing the required scope.
        '404':
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Activity not found
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Activity not found.
      security:
      - bearerAuth: []
      summary: Get an Activity
      tags:
      - Activities
components:
  schemas:
    V1ActivityEntityPayload:
      properties:
        entity_id:
          type: string
        entity_type:
          enum:
          - account
          - contact
          - deal
          - lead
          type: string
        role:
          oneOf:
          - type: string
          - type: 'null'
      required:
      - entity_id
      - entity_type
      - role
      title: V1ActivityEntityPayload
      type: object
    V1ActivityListPayload:
      description: Paginated list response for Activities.
      properties:
        data:
          items:
            $ref: '#/components/schemas/V1ActivityListItemPayload'
          type: array
        pagination:
          $ref: '#/components/schemas/V1PaginationPayload'
      required:
      - data
      - pagination
      title: V1ActivityListPayload
      type: object
    V1ActivityDetailResponsePayload:
      description: Single-Activity response envelope.
      properties:
        data:
          $ref: '#/components/schemas/V1ActivityDetailPayload'
      required:
      - data
      title: V1ActivityDetailResponsePayload
      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
    V1ActivityDetailPayload:
      properties:
        actor:
          oneOf:
          - $ref: '#/components/schemas/V1ActivityActorPayload'
          - type: 'null'
        content:
          oneOf:
          - type: string
          - type: 'null'
        created_at:
          example: '2026-03-22T14:00:01Z'
          oneOf:
          - example: '2026-03-22T14:00:01Z'
            format: date-time
            type: string
          - example: '2026-03-22T14:00:01Z'
            type: 'null'
        entities:
          items:
            $ref: '#/components/schemas/V1ActivityEntityPayload'
          type: array
        external_id:
          description: Client-supplied idempotency key for custom Activities.
          example: invoice-1042
          oneOf:
          - description: Client-supplied idempotency key for custom Activities.
            example: invoice-1042
            type: string
          - description: Client-supplied idempotency key for custom Activities.
            example: invoice-1042
            type: 'null'
        id:
          description: Opaque `activity_` identifier.
          example: activity_3Q8jXRFuLpTQ3nM4PkGvW5
          type: string
        occurred_at:
          example: '2026-03-22T14:00:00Z'
          oneOf:
          - example: '2026-03-22T14:00:00Z'
            format: date-time
            type: string
          - example: '2026-03-22T14:00:00Z'
            type: 'null'
        title:
          oneOf:
          - type: string
          - type: 'null'
        type:
          type: string
        updated_at:
          example: '2026-03-22T14:00:01Z'
          oneOf:
          - example: '2026-03-22T14:00:01Z'
            format: date-time
            type: string
          - example: '2026-03-22T14:00:01Z'
            type: 'null'
      required:
      - actor
      - content
      - created_at
      - entities
      - external_id
      - id
      - occurred_at
      - title
      - type
      - updated_at
      title: V1ActivityDetailPayload
      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
    V1ActivityListItemPayload:
      properties:
        actor:
          oneOf:
          - $ref: '#/components/schemas/V1ActivityActorPayload'
          - type: 'null'
        content:
          oneOf:
          - type: string
          - type: 'null'
        created_at:
          example: '2026-03-22T14:00:01Z'
          oneOf:
          - example: '2026-03-22T14:00:01Z'
            format: date-time
            type: string
          - example: '2026-03-22T14:00:01Z'
            type: 'null'
        entities:
          items:
            $ref: '#/components/schemas/V1ActivityEntityPayload'
          type: array
        external_id:
          description: Client-supplied idempotency key for custom Activities.
          example: invoice-1042
          oneOf:
          - description: Client-supplied idempotency key for custom Activities.
            example: invoice-1042
            type: string
          - description: Client-supplied idempotency key for custom Activities.
            example: invoice-1042
            type: 'null'
        id:
          description: Opaque `activity_` identifier.
          example: activity_3Q8jXRFuLpTQ3nM4PkGvW5
          type: string
        occurred_at:
          example: '2026-03-22T14:00:00Z'
          oneOf:
          - example: '2026-03-22T14:00:00Z'
            format: date-time
            type: string
          - example: '2026-03-22T14:00:00Z'
            type: 'null'
        title:
          oneOf:
          - type: string
          - type: 'null'
        type:
          type: string
        updated_at:
          example: '2026-03-22T14:00:01Z'
          oneOf:
          - example: '2026-03-22T14:00:01Z'
            format: date-time
            type: string
          - example: '2026-03-22T14:00:01Z'
            type: 'null'
      required:
      - actor
      - content
      - created_at
      - entities
      - external_id
      - id
      - occurred_at
      - title
      - type
      - updated_at
      title: V1ActivityListItemPayload
      type: object
    V1CreateActivityRequest:
      description: Request body for creating a custom Activity.
      properties:
        account_id:
          description: Opaque `account_` identifier.
          example: account_7B5jXRFuLpTQ3nM4PkGvW2
          oneOf:
          - description: Opaque `account_` identifier.
            example: account_7B5jXRFuLpTQ3nM4PkGvW2
            type: string
          - description: Opaque `account_` identifier.
            example: account_7B5jXRFuLpTQ3nM4PkGvW2
            type: 'null'
        body:
          oneOf:
          - type: string
          - type: 'null'
        contact_id:
          description: Opaque `contact_` identifier.
          example: contact_6M4jXRFuLpTQ3nM4PkGvW8
          oneOf:
          - description: Opaque `contact_` identifier.
            example: contact_6M4jXRFuLpTQ3nM4PkGvW8
            type: string
          - description: Opaque `contact_` identifier.
            example: contact_6M4jXRFuLpTQ3nM4PkGvW8
            type: 'null'
        deal_id:
          description: Opaque `deal_` identifier.
          example: deal_5N2jXRFuLpTQ3nM4PkGvW7
          oneOf:
          - description: Opaque `deal_` identifier.
            example: deal_5N2jXRFuLpTQ3nM4PkGvW7
            type: string
          - description: Opaque `deal_` identifier.
            example: deal_5N2jXRFuLpTQ3nM4PkGvW7
            type: 'null'
        external_id:
          description: Client-supplied idempotency key for custom Activities.
          example: invoice-1042
          oneOf:
          - description: Client-supplied idempotency key for custom Activities.
            example: invoice-1042
            type: string
          - description: Client-supplied idempotency key for custom Activities.
            example: invoice-1042
            type: 'null'
        occurred_at:
          example: '2026-03-22T14:00:00Z'
          format: date-time
          type: string
        title:
          type: string
        type:
          type: string
      required:
      - occurred_at
      - title
      - type
      title: V1CreateActivityRequest
      type: object
    V1ActivityActorPayload:
      properties:
        name:
          oneOf:
          - type: string
          - type: 'null'
      required:
      - name
      title: V1ActivityActorPayload
      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