decide-fyi CRM Sync API

openapi: 3.2.0
info:
  title: Decide Decision CRM Sync API
  summary: Decision protocol for state-changing software actions.
  description: Call Decide before products, agents, queues, billing systems, CRMs, or internal tools change state. The API returns a signed Decision Record v1 object with policy bundle attestation, evidence, action binding, replay, verification handles, portable Decision Packet v1 exports, simulation-only counterfactual analysis, cryptographic audit chains, Action Execution Receipts, Outcome Records, CRM Sync Records, predictive confidence, first-party policy pattern templates, policy effectiveness metrics, opt-in anonymized benchmarks, and explainable anomaly reports derived from reported outcomes.
  version: 1.13.0
  x-decision-protocol-version: decision_protocol_v1
  x-decision-record-version: decision_record_v1
  x-decision-packet-version: decision_packet_v1
servers:
- url: https://www.decide.fyi
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: CRM Sync
  description: Record CRM write-back and inbound sync receipts linked to Decision Records.
paths:
  /api/decision/{decision_id}/crm-sync:
    post:
      tags:
      - CRM Sync
      operationId: recordDecisionCrmSync
      summary: Record a Decision CRM Sync receipt
      description: 'Creates a hashed CRM Sync Record linked to the original Decision Record. Keyed writes are atomically claimed: the same key plus the same canonical CRM sync payload replays the original receipt, a concurrent request returns 409 in progress, and the same key plus a different payload returns 409 conflict. Authoritative storage and idempotency failures return 503 without acknowledging an untracked sync receipt.'
      parameters:
      - $ref: '#/components/parameters/DecisionId'
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionCrmSyncRequest'
            examples:
              salesforceWriteback:
                summary: Salesforce opportunity write-back
                value:
                  sync_status: written
                  sync_direction: writeback
                  crm_provider: salesforce
                  crm_object_type: Opportunity
                  crm_object_id: 006xx000004TmiQAAS
                  crm_record_url: https://example.my.salesforce.com/006xx000004TmiQAAS
                  decision_record_hash: 7f3a...
                  decision_receipt_hash: c91e...
                  decision_verdict: 'yes'
                  decision_action: approve_discount
                  policy_id: pricing_exception
                  policy_version: v3
      responses:
        '200':
          description: Idempotent replay of an existing Decision CRM Sync receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionCrmSyncResult'
        '201':
          description: Decision CRM Sync recorded
          headers:
            x-decision-crm-sync-id:
              schema:
                type: string
            x-decision-crm-sync-hash:
              schema:
                type: string
            x-idempotency-status:
              schema:
                type: string
                enum:
                - created
                - replayed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionCrmSyncResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Decision not found in the authenticated caller scope
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      tags:
      - CRM Sync
      operationId: listDecisionCrmSyncs
      summary: List Decision CRM Sync receipts for a decision
      parameters:
      - $ref: '#/components/parameters/DecisionId'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      responses:
        '200':
          description: Decision CRM Sync receipt list
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - decision_id
                - count
                - crm_syncs
                properties:
                  ok:
                    type: boolean
                  decision_id:
                    type: string
                  count:
                    type: integer
                  crm_syncs:
                    type: array
                    items:
                      $ref: '#/components/schemas/DecisionCrmSync'
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Decision not found in the authenticated caller scope
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    IdempotencyConflict:
      description: The idempotency key is already in progress, or it was reused with a different canonical payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API key missing, invalid, inactive, or unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Decision storage or the upstream decision engine timed out or is temporarily unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    DecisionCrmSyncResult:
      type: object
      required:
      - ok
      - decision_id
      - crm_sync
      properties:
        ok:
          type: boolean
        idempotency_status:
          type: string
        decision_id:
          type: string
        crm_sync:
          $ref: '#/components/schemas/DecisionCrmSync'
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        c:
          type: string
        v:
          type: string
        request_id:
          type: string
        error:
          type: string
        message:
          type: string
      additionalProperties: true
    DecisionCrmSyncRequest:
      type: object
      required:
      - sync_status
      - crm_provider
      - crm_object_type
      - crm_object_id
      properties:
        decision_id:
          type: string
          maxLength: 600
        sync_status:
          type: string
          description: Normalized to queued, written, failed, skipped, stale, unknown, or a compact custom status.
        sync_direction:
          type: string
          enum:
          - writeback
          - inbound
          - bidirectional
        crm_provider:
          type: string
          examples:
          - salesforce
          - hubspot
          - generic
        crm_object_type:
          type: string
        crm_object_id:
          type: string
        crm_record_url:
          type: string
        field_mapping:
          type: object
          additionalProperties:
            type: string
        mapped_fields:
          type: object
          additionalProperties: true
        decision_record_hash:
          type: string
        decision_receipt_hash:
          type: string
        decision_verdict:
          type: string
        decision_action:
          type: string
        policy_id:
          type: string
        policy_version:
          type: string
        crm_revision:
          type: string
        crm_modified_at:
          type: string
        reported_at:
          type: string
      additionalProperties: true
    DecisionCrmSync:
      type: object
      required:
      - decision_protocol_version
      - decision_crm_sync_version
      - sync_id
      - decision_id
      - sync_status
      - crm_target
      - sync_hash
      - reported_at
      properties:
        decision_protocol_version:
          type: string
          const: decision_protocol_v1
        decision_crm_sync_version:
          type: string
          const: decision_crm_sync_v1
        sync_id:
          type: string
        decision_id:
          type: string
        idempotency_key:
          type: string
        sync_direction:
          type: string
        sync_status:
          type: string
        crm_target:
          type: object
          additionalProperties: true
        field_mapping:
          type: object
          additionalProperties: true
        mapped_fields:
          type: object
          additionalProperties: true
        decision_values:
          type: object
          additionalProperties: true
        sync_input_hash:
          type: string
        sync_hash:
          type: string
        integrity:
          type: object
          additionalProperties: true
        reported_at:
          type: string
        decision_found:
          type: boolean
        decision_url:
          type: string
        verify_url:
          type: string
      additionalProperties: true
  parameters:
    DecisionId:
      name: decision_id
      in: path
      required: true
      schema:
        type: string
        maxLength: 600
    RequestId:
      name: x-request-id
      in: header
      required: false
      schema:
        type: string
        maxLength: 160
    IdempotencyKey:
      name: x-idempotency-key
      in: header
      required: false
      schema:
        type: string
        maxLength: 300
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key