SendPulse Deal history API

openapi: 3.2.0
info:
  description: Using the API for the CRM service, you can integrate your system with CRM from SendPulse and receive detailed information on pipelines, deals, contacts and their attributes and users.
  title: SendPulse CRM Public Deal history API
  version: 0.1.0
servers:
- url: https://api.sendpulse.com/crm/v1
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: Deal history
paths:
  /deals/{dealId}/history:
    get:
      tags:
      - Deal history
      summary: Deal history
      description: Get deal history by ID within a date range.
      parameters:
      - name: dealId
        in: path
        required: true
        schema:
          type: integer
      - name: fromDate
        in: query
        required: true
        schema:
          type: string
          format: date-time
          example: 2024-12-12 12:12:12+00:00
      - name: toDate
        in: query
        required: true
        schema:
          type: string
          format: date-time
          example: 2024-12-12 12:12:12+00:00
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/DealHistory'
      operationId: getDealHistory
      x-ai-role: crm_sales_analyst
      x-ai-description: Retrieves the full chronological audit trail of all changes made to a specific deal within a defined time window. This endpoint is the primary tool for understanding deal progression, identifying stalled stages, and reconstructing the sales timeline for reporting or debugging purposes.
      x-ai-reasoning-instructions:
      - Verify that the dealId exists before querying history to avoid misleading empty results.
      - Ensure fromDate is earlier than toDate; if the user provides them in the wrong order, swap and notify.
      - When the user asks for 'recent history', default the range to the last 30 days unless they specify otherwise.
      - If the returned history is empty, consider suggesting a wider date range rather than assuming no changes occurred.
      x-ai-responding-instructions:
      - Summarize the key changes in the history (e.g., status transitions, owner reassignments, value updates) rather than listing raw events.
      - Highlight any unusual patterns such as rapid stage changes or prolonged inactivity within the range.
      - If the range returns many events, group them by type or date for better readability.
      - Suggest follow-up actions such as updating the deal or contacting the assigned manager if the history reveals a stalled state.
      x-ai-suggestions:
      - Use a 30-day lookback window as a default starting point for deal audits.
      - Combine with getDeal to cross-reference current deal state with its historical changes.
      - Use this endpoint for generating sales pipeline health reports.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
components:
  schemas:
    DealHistory:
      type: object
      properties:
        id:
          type: integer
        userId:
          type: integer
        eventData:
          type: array
        eventType:
          type: string
        eventTime:
          type: string
          format: date-time
        currentData:
          type: object
          properties:
            contactFirstName:
              type: string
            contactLastName:
              type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Static API Key authentication.  A long-lived token generated manually in the SendPulse account settings.

        '
      x-ai-description: 'Permanent authentication token. Ideal for simple integrations without token refresh logic.

        '
    outh2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for temporary access tokens.
      flows:
        clientCredentials:
          tokenUrl: https://api.sendpulse.com/oauth/access_token
          scopes: {}
      x-ai-description: 'Standard OAuth 2.0 flow using Client ID and Client Secret.  Provides temporary tokens (valid for 1 hour) for enhanced security.

        '