SendPulse Deal contacts 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 contacts API
  version: 0.1.0
servers:
- url: https://api.sendpulse.com/crm/v1
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: Deal contacts
paths:
  /deals/{dealId}/contacts:
    get:
      tags:
      - Deal contacts
      summary: Get a list of contacts in a deal
      description: Returns a list of contacts in the specified deal
      parameters:
      - name: dealId
        in: path
        required: true
        description: Deal ID for which you want to get the list of contacts. It can be obtained with the "Get a list of deals" method
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
      operationId: getDealContacts
      x-ai-role: crm_sales_specialist
      x-ai-description: Retrieves all contacts associated with a specific deal in the CRM pipeline. A deal in SendPulse CRM can have multiple contacts linked to it — this endpoint exposes that relationship, enabling agents to understand who the stakeholders are in a given sales opportunity before taking further action (e.g., sending follow-ups or updating contact data).
      x-ai-reasoning-instructions:
      - Ensure the dealId is valid before calling — use 'Get a list of deals' to obtain it if not already known.
      - If the response returns an empty array, inform the user that no contacts are linked to this deal yet and suggest adding contacts.
      - Consider whether the user needs full contact details — this endpoint returns contact objects, but related endpoints may provide richer profile data.
      x-ai-responding-instructions:
      - List the contacts by name (or identifier) returned in the response for clarity.
      - If multiple contacts are returned, summarize the count and highlight key identifiers.
      - Suggest logical next steps such as updating contact info, sending a campaign, or viewing the deal details.
      x-ai-suggestions:
      - Use the returned contact IDs to fetch full contact profiles via the Contacts endpoints.
      - Cross-reference these contacts with mailing lists to check if they are already subscribed.
      - If no contacts are found, use the 'Add contact to deal' endpoint to link relevant contacts.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
  /deals/{dealId}/contacts/{contactId}:
    post:
      tags:
      - Deal contacts
      summary: Add a contact to a deal
      description: Adds a previously created contact to the specified deal
      parameters:
      - name: dealId
        in: path
        required: true
        description: Deal ID in which you want to add the contact. It can be obtained with the "Get a list of deals" method
        schema:
          type: integer
      - name: contactId
        in: path
        required: true
        description: Contact ID you want to add to the deal. It can be obtained with the "Get a list of contacts" method
        schema:
          type: integer
      responses:
        '201':
          description: ''
      operationId: addContactToDeal
      x-ai-role: crm_pipeline_specialist
      x-ai-description: Links an existing contact to a specific deal, establishing a relationship between a person and a sales opportunity. This is a structural association endpoint — both the contact and the deal must already exist. It is typically used after deal creation to assign responsible parties, prospects, or stakeholders to the pipeline item.
      x-ai-reasoning-instructions:
      - Verify that the deal exists before attempting to link — use 'Get a list of deals' to confirm dealId is valid.
      - Verify that the contact exists before linking — use 'Get a list of contacts' to confirm contactId.
      - Check whether the contact is already associated with this deal to avoid duplicate associations.
      - Consider whether the contact's role in the deal (prospect, decision-maker, stakeholder) should be tracked separately via a dedicated field or note.
      x-ai-responding-instructions:
      - On success (201), confirm which contact was linked to which deal by referencing both IDs.
      - Suggest reviewing the deal's full contact list as a follow-up using the appropriate GET endpoint.
      - If a 404 or validation error occurs, clarify which resource (deal or contact) was not found and guide the user to retrieve the correct ID.
      x-ai-suggestions:
      - First retrieve available deals via 'Get a list of deals', then contacts via 'Get a list of contacts' before calling this endpoint.
      - After linking, consider adding a note or task to the deal to document the contact's role.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - RelationshipCreate
    delete:
      tags:
      - Deal contacts
      summary: Delete a contact from a deal
      description: Removes the contact from the specified deal
      parameters:
      - name: dealId
        in: path
        required: true
        description: Deal ID from which you want to remove the contact. It can be obtained with the "Get a list of deals" method
        schema:
          type: integer
      - name: contactId
        in: path
        required: true
        description: Contact ID you want to remove from the deal. It can be obtained with the "Get a list of contacts" method
        schema:
          type: integer
      responses:
        '204':
          description: ''
      operationId: removeDealContact
      x-ai-role: crm_deal_manager
      x-ai-description: Disassociates a contact from a deal without deleting either entity. Use this when a person is no longer relevant to a specific sales opportunity — for example, when a stakeholder changes or a contact was added by mistake. The deal and contact continue to exist independently.
      x-ai-reasoning-instructions:
      - Confirm the dealId is valid by cross-referencing with 'Get a list of deals' before attempting removal.
      - Confirm the contactId is currently associated with the specified deal to avoid misleading 404 errors.
      - Warn the user that this action only unlinks the contact from the deal — it does not delete the contact from the CRM.
      - If the user intends to remove the last contact from a deal, note that the deal may become ownerless or harder to track.
      x-ai-responding-instructions:
      - On success (204), confirm that the contact has been unlinked from the deal, not deleted.
      - If the deal or contact is not found, clarify which ID caused the issue and suggest how to retrieve valid IDs.
      - Suggest using 'Get a list of deal contacts' to verify the updated contact list after removal.
      x-ai-suggestions:
      - Use 'Get a list of deals' to retrieve a valid dealId before calling this endpoint.
      - Use 'Get a list of contacts' to retrieve a valid contactId.
      - After removal, call the deal contacts list endpoint to confirm the association no longer exists.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: This will remove the contact from the deal. The contact record itself will not be deleted.
        security_info:
          data_handling:
          - RelationshipDelete
components:
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: integer
          description: Contact ID
        userId:
          type: integer
          description: ID of user who created the contact
        sourceType:
          type: string
          enum:
          - manually
          - chatbot
          - subscription_form
          - landing
          - a360
          - payments
        responsibleId:
          type: integer
          description: ID of user responsible for the contact. Can be obtained in the “Get list of invited users” method
        firstName:
          type: string
          description: Contact first name
        lastName:
          type: string
          description: Contact last name
        dealsQty:
          type: integer
        externalContactId:
          type: string
        comments:
          items:
            $ref: '#/components/schemas/ContactComment'
        tags:
          items:
            $ref: '#/components/schemas/ContactTag'
        phones:
          items:
            $ref: '#/components/schemas/ContactPhone'
        emails:
          items:
            $ref: '#/components/schemas/ContactEmail'
        messengers:
          items:
            $ref: '#/components/schemas/ContactMessenger'
        attributes:
          items:
            $ref: '#/components/schemas/ContactAttributeValue'
        history:
          items:
            $ref: '#/components/schemas/ContactHistory'
        tasks:
          type: array
          items:
            type: integer
        createdAt:
          type: string
          format: date-time
          description: The date and time the contact was created. Output in YYYY-MM-DD hh:mm:ss format with fractions of a second and time zone
        updatedAt:
          type: string
          format: date-time
        attachments:
          $ref: '#/components/schemas/EntityAttachment'
    ContactEmail:
      type: object
      properties:
        id:
          type: integer
          description: Email address ID
        email:
          type: string
          description: Email address
        isMain:
          type: boolean
          description: Determines whether the email address is the main one
    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
    ContactAttributeValue:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: integer
          description: '| Status

            * 0 — inactive (deleted by user) * 1 — active * 2 — hidden'
        type:
          type: integer
        mandatory:
          type: boolean
        contactCardShow:
          type: boolean
        order:
          type: integer
        options:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
          description: Items of "List" field type
        value:
          properties:
            type:
              type: string
              description: Field type
            value:
              type: string
              description: Field value
          description: ''
        default:
          type: boolean
          description: ''
    ContactPhone:
      type: object
      properties:
        id:
          type: integer
          description: Contact phone ID
        phone:
          type: string
        isMain:
          type: boolean
    ContactTag:
      type: object
      properties:
        id:
          type: integer
          description: Tag ID
        name:
          type: string
          description: Tag name
        colorText:
          type: string
        colorBackground:
          type: string
        contactCount:
          type: integer
          description: Number of contacts associated with the tag
        taskCount:
          type: integer
          description: Number of tasks associated with a tag
    EntityAttachment:
      type: object
      properties:
        id:
          type: integer
        link:
          type: string
        entityId:
          type: number
        entityType:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
    ContactComment:
      type: object
      properties:
        id:
          type: integer
        userId:
          type: integer
        text:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        attachments:
          $ref: '#/components/schemas/EntityAttachment'
        childCount:
          type: integer
        childUsers:
          type: array
          items:
            type: integer
    ContactMessenger:
      type: object
      properties:
        id:
          type: integer
          description: ID of the added messenger
        typeId:
          type: integer
          description: Messenger type
        login:
          type: string
          description: Contact login in the specified messenger
        botId:
          type: string
          description: External bot ID
        contactId:
          type: string
          description: External contact ID
        status:
          type: integer
        chatbotUrl:
          type: string
          description: URL of the chatbot from which the contact was received
        isMainChatbot:
          type: boolean
          description: Determine if chatbot messenger is the main one
  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.

        '