SendPulse Custom Tab 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 Custom Tab API
  version: 0.1.0
servers:
- url: https://api.sendpulse.com/crm/v1
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
  name: Custom Tab
paths:
  /custom-tab:
    get:
      tags:
      - Custom Tab
      summary: Get all users custom tabs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomTabWithAttribute'
                  pipeline:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomTabWithAttribute'
                  board:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomTabWithAttribute'
                  company:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomTabWithAttribute'
      operationId: getCustomTabs
      x-ai-role: crm_configuration_specialist
      x-ai-description: Retrieves all custom tab definitions configured for the current user account, organized by entity type. Custom tabs extend the default CRM interface by adding domain-specific views to contacts, pipelines, boards, and companies. This endpoint is the entry point for understanding what custom UI structure is active before rendering or modifying CRM entities.
      x-ai-reasoning-instructions:
      - Use this endpoint to discover available custom tabs before attempting to create or update tab configurations.
      - Check all four entity categories (contact, pipeline, board, company) even if only one is needed — the full structure prevents stale UI assumptions.
      - If the response arrays are empty, it means no custom tabs have been defined yet — suggest creating them rather than assuming a default layout.
      x-ai-responding-instructions:
      - Present the tabs grouped by entity type (contact, pipeline, board, company) for clarity.
      - Highlight the total count per entity to help the user understand the current configuration scope.
      - If any entity has no tabs, explicitly note it as unconfigured rather than omitting it from the response summary.
      x-ai-suggestions:
      - Use the returned tab IDs as references when creating or updating specific custom tab entries.
      - If tabs are missing for an entity, suggest using the corresponding POST endpoint to create them.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
    post:
      tags:
      - Custom Tab
      summary: Create custom tab
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of custom tab
                entityType:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  description: 0 - contact, 1 - pipeline, 2 - board, 3 - company
                entityId:
                  type: integer
                  description: Related entity ID. Only for pipelines and boards
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomTab'
      operationId: createCustomTab
      x-ai-role: crm_configuration_specialist
      x-ai-description: Creates a custom tab that extends the UI and data model of a specific CRM entity (contact, pipeline, board, or company). Custom tabs allow teams to attach domain-specific views and structured data sections directly to core CRM objects, enabling tailored workflows without modifying the base schema.
      x-ai-reasoning-instructions:
      - 'Clarify the target entity type before proceeding: 0=contact, 1=pipeline, 2=board, 3=company.'
      - If entityType is 1 (pipeline) or 2 (board), require entityId — it is mandatory for those types.
      - For entityType 0 (contact) or 3 (company), entityId is typically not needed; warn the user if they provide it unexpectedly.
      - Check whether a tab with the same name already exists on the target entity to prevent duplicates.
      - Use a descriptive, purpose-reflecting name (e.g., 'Billing Info', 'Deal Checklist') rather than generic labels.
      x-ai-responding-instructions:
      - Confirm creation by referencing the returned CustomTab ID and the entity it was attached to.
      - If entityType requires entityId and it was omitted, explain the constraint clearly.
      - Suggest adding fields or sections to the newly created tab as an immediate next step.
      x-ai-suggestions:
      - Billing Details
      - Onboarding Checklist
      - Technical Requirements
      - SLA Tracking
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ResourceStateUpdate
  /custom-tab/{customTabId}:
    put:
      tags:
      - Custom Tab
      summary: Update custom tabs
      parameters:
      - name: customTabId
        in: path
        required: true
        schema:
          type: number
        description: Custom tab ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                order:
                  type: integer
                  description: Custom tab order
                name:
                  type: string
                  description: Custom tab name
                isVisible:
                  type: boolean
                  description: Indicates whether the entity is visible to users
                entityType:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  description: 0 - contact, 1 - pipeline, 2 - board, 3 - company
                entityId:
                  type: integer
                  description: Related entity ID. Only for pipelines and boards
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomTab'
      operationId: updateCustomTab
      x-ai-role: crm_interface_designer
      x-ai-description: Modifies the configuration of a custom tab in the CRM interface. Custom tabs extend the default UI by surfacing context-specific data (contacts, pipelines, boards, companies) directly within a record view. Updating a tab's visibility, order, or entity binding allows teams to tailor the workspace layout to their workflow without creating new tabs.
      x-ai-reasoning-instructions:
      - Retrieve the current tab configuration first to avoid overwriting fields that are not being changed.
      - If `entityType` is 0 (contact) or 3 (company), `entityId` is not applicable — do not include it in the payload.
      - If `entityType` is 1 (pipeline) or 2 (board), `entityId` is required — validate its presence before making the call.
      - Changing `isVisible` to false hides the tab from all users; confirm the intent if the action was not explicitly requested.
      - Check that `order` value does not conflict with other tabs' ordering to avoid unexpected reordering side effects.
      x-ai-responding-instructions:
      - Confirm which fields were updated and reflect the new values back to the user.
      - If `isVisible` was set to false, warn the user that the tab will no longer appear in the UI for any user.
      - Suggest verifying the updated tab by fetching the current tab list or reloading the relevant entity view.
      x-ai-suggestions:
      - 'Set `isVisible: false` to temporarily hide a tab without deleting it.'
      - Use `order` to reposition the tab relative to other custom tabs on the same entity.
      - To reassign a tab from one pipeline to another, update both `entityType` (1) and `entityId` together.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          reason: Setting isVisible to false affects all users; entity reassignment may cause data display inconsistencies.
        security_info:
          data_handling:
          - ResourceStateUpdate
    delete:
      tags:
      - Custom Tab
      summary: Delete custom tabs
      parameters:
      - name: customTabId
        in: path
        required: true
        schema:
          type: number
        description: Custom tab ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entityType:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  description: 0 - contact, 1 - pipeline, 2 - board, 3 - company
                entityId:
                  type: integer
                  description: Related entity ID. Only for pipelines and boards
      responses:
        '204':
          description: deleted
      operationId: deleteCustomTab
      x-ai-role: crm_configuration_specialist
      x-ai-description: Permanently removes a custom tab from a CRM entity view. Custom tabs are UI extensions that group custom fields — deleting one affects the display layer for all users with access to the related entity type (contact, pipeline, board, or company). This is a destructive, non-reversible action with potential UX impact across the team.
      x-ai-reasoning-instructions:
      - Confirm the customTabId is valid and belongs to the expected entity type before proceeding.
      - Warn the user that deletion is permanent and will affect the interface for all team members who use this entity type.
      - For pipelines (entityType=1) and boards (entityType=2), verify that entityId is provided — it is required for those contexts.
      - For contacts (entityType=0) and companies (entityType=3), entityId is not needed; clarify this if the user provides one unnecessarily.
      - If the tab contains active custom fields, inform the user that those fields may become inaccessible or lose their display context.
      x-ai-responding-instructions:
      - Confirm the deletion with reference to the customTabId that was removed.
      - Mention the affected entity type in the confirmation to avoid ambiguity.
      - If the response is 204 No Content, explicitly state that the operation was successful despite no body being returned.
      - Suggest reviewing remaining custom tabs via a list endpoint if the user needs to verify the current configuration.
      x-ai-suggestions:
      - Use this after confirming the tab is no longer needed across all team workflows.
      - Consider exporting or documenting existing custom field configurations before deletion.
      - Follow up with a list of remaining custom tabs to confirm the desired state.
      x-ai-capabilities:
        confirmation:
          type: Required
          message: This action permanently deletes the custom tab and cannot be undone. Confirm before proceeding.
        security_info:
          data_handling:
          - ResourceDestruction
          - IrreversibleAction
  /custom-tab/{customTabId}/relation:
    post:
      tags:
      - Custom Tab
      summary: Add new relation with attribute
      parameters:
      - name: customTabId
        in: path
        required: true
        schema:
          type: number
        description: Custom tab ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entityType:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  description: 0 - contact, 1 - pipeline, 2 - board, 3 - company
                entityId:
                  type: integer
                  description: Related entity ID. Only for pipelines and boards
                entityIds:
                  type: array
                  items:
                    type: integer
                  description: Related attributes IDs.
      responses:
        '200':
          description: OK
      operationId: addCustomTabRelation
      x-ai-role: crm_data_architect
      x-ai-description: Links a CRM entity (contact, pipeline, board, or company) to a specific custom tab, enabling contextual data grouping and cross-entity relationships. This is the binding operation that makes custom tab attributes visible and filterable in the context of a chosen entity type.
      x-ai-reasoning-instructions:
      - 'Determine the entityType before calling: 0=contact, 1=pipeline, 2=board, 3=company.'
      - For pipelines (1) and boards (2), provide a single entityId; for contacts and companies, use entityIds array.
      - Verify the customTabId exists before attempting to add a relation to avoid 404 errors.
      - Avoid duplicate relations — check existing relations for this tab and entity combination if idempotency is required.
      x-ai-responding-instructions:
      - Confirm which entity type and ID(s) were linked to the custom tab.
      - If the operation succeeds, suggest verifying the relation by retrieving the custom tab's relations.
      - If an error occurs, clarify whether the issue is with the customTabId, entityType mismatch, or invalid entityId(s).
      x-ai-suggestions:
      - Use entityType=0 with entityIds to bulk-link multiple contacts to the tab.
      - Use entityType=1 or entityType=2 with a single entityId for pipeline/board-scoped tabs.
      - After adding relations, retrieve the tab data to confirm the binding is reflected.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ResourceStateUpdate
    delete:
      tags:
      - Custom Tab
      summary: Delete relation with attribute
      parameters:
      - name: customTabId
        in: path
        required: true
        schema:
          type: number
        description: Custom tab ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entityType:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  description: 0 - contact, 1 - pipeline, 2 - board, 3 - company
                entityId:
                  type: integer
                  description: Related entity ID. Only for pipelines and boards
                entityIds:
                  type: array
                  items:
                    type: integer
                  description: Related attributes IDs.
      responses:
        '200':
          description: OK
      operationId: deleteCustomTabRelation
      x-ai-role: crm_data_architect
      x-ai-description: Removes the association between a custom tab and one or more related entities (contacts, pipelines, boards, or companies). This operation detaches the tab's visibility or binding from the specified entity scope — it does not delete the tab itself or the entities, only the relational link between them.
      x-ai-reasoning-instructions:
      - 'Clarify entityType before proceeding: 0=contact, 1=pipeline, 2=board, 3=company — wrong type silently targets the wrong scope.'
      - entityId is applicable only for pipelines (1) and boards (2); for contacts (0) and companies (3) use entityIds only.
      - entityIds holds attribute IDs to unlink, not entity IDs — confirm the user understands the difference before executing.
      - Deletion of relations is irreversible; if the user is unsure, suggest listing current relations first.
      - If entityIds is empty or omitted, ask for clarification — the behavior with an empty array may be a no-op or remove all relations.
      x-ai-responding-instructions:
      - Confirm which relations were removed by echoing back the entityType label (e.g., 'pipeline') and the affected IDs.
      - Clarify that the custom tab and the entities themselves remain intact — only the link was deleted.
      - If the operation succeeds, suggest verifying the tab configuration or re-linking with a different set of attributes if needed.
      x-ai-suggestions:
      - Use entityType=1 with entityId to unlink a specific pipeline from this tab.
      - Use entityType=0 with entityIds to batch-remove contact attribute relations.
      - To inspect current relations before deleting, retrieve the custom tab details first.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: This will permanently remove the specified relations from the custom tab. Proceed?
        security_info:
          data_handling:
          - RelationDelete
components:
  schemas:
    CustomTabWithAttribute:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Custom tab name
        userId:
          type: integer
          description: Custom tab owner
        isVisible:
          type: boolean
          description: Indicates whether the entity is visible to users
        isDefault:
          type: boolean
          description: Indicates whether the entity is default and cannot be changed
        type:
          type: integer
          enum:
          - 0
          - 1
          description: 0 - attributes, 1 - integration
        entityType:
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 3
          description: 0 - contact, 1 - pipeline, 2 - board, 3 - companies
        entityId:
          type: integer
          description: Related entity ID. Only for boards and pipelines
        attributes:
          type: array
          items:
            type: object
            properties:
              attributeId:
                type: integer
              attributeType:
                type: integer
    CustomTab:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Custom tab name
        userId:
          type: integer
          description: Custom tab owner
        isVisible:
          type: boolean
          description: Indicates whether the entity is visible to users
        isDefault:
          type: boolean
          description: Indicates whether the entity is default and cannot be changed
        type:
          type: integer
          enum:
          - 0
          - 1
          description: 0 - attributes, 1 - integration
        entityType:
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 3
          description: 0 - contact, 1 - pipeline, 2 - board, 3 - company
        entityId:
          type: integer
          description: Related entity ID. Only for boards and pipelines
  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.

        '