SendPulse Contact 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 Contact history API
  version: 0.1.0
servers:
- url: https://api.sendpulse.com/crm/v1
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: Contact history
paths:
  /contacts/{contactId}/history:
    get:
      tags:
      - Contact history
      summary: Contact history
      description: Get contact history by ID within a date range.
      parameters:
      - name: contactId
        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: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContactHistory'
      operationId: getContactHistory
      x-ai-role: crm_data_analyst
      x-ai-description: Retrieves the full interaction timeline for a specific contact within a defined date window. This endpoint is the primary audit trail for understanding what happened to a contact — what messages were sent, what automations were triggered, and how the contact responded. Use it for debugging campaign flows, auditing contact activity, or building timeline views in CRM interfaces.
      x-ai-reasoning-instructions:
      - Verify that `fromDate` is earlier than `toDate` before making the request.
      - If the user asks for 'recent history', default the range to the last 30 days unless specified otherwise.
      - Note that date-time values must include time component — if only a date is provided, append 00:00:00 for `fromDate` and 23:59:59 for `toDate`.
      - Large date ranges may return extensive arrays — advise the user to narrow the range if performance is a concern.
      - If contactId is unknown, suggest resolving it first via a contact search endpoint.
      x-ai-responding-instructions:
      - Summarize the number of history entries returned and the date range covered.
      - Highlight any notable event types (e.g., unsubscribes, bounces, automation triggers) if present in the results.
      - If the array is empty, clarify that no activity was recorded in the given range — not that the contact doesn't exist.
      - Suggest narrowing or widening the date range if the result set seems unexpectedly small or large.
      x-ai-suggestions:
      - Use a 7-day window for recent activity checks.
      - Use a 30-day window for monthly campaign audits.
      - Combine with contact details endpoint to build a full contact profile view.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
components:
  schemas:
    ContactHistory:
      type: object
      properties:
        id:
          type: integer
        userId:
          type: integer
        contactId:
          type: integer
        eventType:
          type: string
        eventTime:
          type: string
          format: date-time
        eventData:
          type: object
          properties:
            dealName:
              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.

        '