SendPulse Board attributes 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 Board attributes API
  version: 0.1.0
servers:
- url: https://api.sendpulse.com/crm/v1
security:
- apiKey: []
- oauth2: []
tags:
- name: Board attributes
paths:
  /boards/{boardId}/attributes:
    get:
      tags:
      - Board attributes
      summary: Get attribute for board
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/BoardAttribute'
      operationId: getBoardAttributes
      x-ai-role: crm_data_architect
      x-ai-description: Retrieves the custom attribute schema defined for a specific CRM board. Board attributes act as column definitions — they determine what structured data can be stored per card/contact on that board. Understanding the attribute schema is a prerequisite before creating or updating cards, as it defines valid field names, types, and constraints.
      x-ai-reasoning-instructions:
      - Always fetch board attributes before attempting to create or update cards on a board — attribute IDs and types are required for correct field mapping.
      - If the boardId is unknown, first call the board listing endpoint to resolve the correct ID.
      - Cache the attribute schema locally within a session to avoid redundant calls when processing multiple cards on the same board.
      x-ai-responding-instructions:
      - Present the attributes as a structured field reference — name, type, and ID for each attribute.
      - If the attribute list is empty, inform the user that no custom fields have been configured for this board yet and suggest creating them.
      - Highlight any required attributes the user must populate when creating cards.
      x-ai-suggestions:
      - Use returned attribute IDs when constructing payloads for card create/update endpoints.
      - Follow up with a card listing call to see how current data maps to these attributes.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
    post:
      tags:
      - Board attributes
      summary: Create attribute for board
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                  description: Attribute name
                type:
                  type: number
                  description: 'Attribute type:

                    0 -string

                    1 - number

                    2 - date

                    3 - link

                    4 - list

                    5 - multiList

                    '
                mandatory:
                  type: boolean
                  description: Is attribute required
                options:
                  type: array
                  description: Attribute options (only for "list" and "multiList" types)
                  default:
                  - 1
                  - 2
      responses:
        '201':
          description: Successfully
      operationId: createBoardAttribute
      x-ai-role: crm_data_architect
      x-ai-description: 'Defines a custom attribute schema for a CRM board, extending its data model beyond built-in fields. Attributes act as typed column definitions — they determine what structured data can be captured per contact or deal on this board. Choosing the correct type upfront is critical: it cannot be changed after contacts have values assigned.'
      x-ai-reasoning-instructions:
      - Before creating, check existing attributes on the board to avoid name collisions.
      - 'Validate that `type` matches the expected data semantics: use `date` for timestamps, `link` for URLs, `list`/`multiList` for constrained vocabularies.'
      - If `type` is 4 (list) or 5 (multiList), `options` is required — warn the user if it is missing or empty.
      - If `mandatory` is true, ensure the user understands all existing contacts will lack this value until backfilled.
      - Suggest snake_case or consistent naming conventions for `name` to simplify downstream filtering.
      x-ai-responding-instructions:
      - Confirm the attribute was created and echo back its name and type for clarity.
      - If type is list or multiList, summarize the options that were registered.
      - Suggest populating the attribute via contact update endpoints as an immediate next step.
      - If a 4xx error occurs due to a duplicate name, propose a disambiguated alternative.
      x-ai-suggestions:
      - industry
      - deal_stage
      - onboarding_date
      - contract_url
      - preferred_contact_channel
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - SchemaModification
          - ResourceStateUpdate
  /boards/{boardId}/attributes/{attributeId}:
    put:
      tags:
      - Board attributes
      summary: Update attribute for board
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: integer
      - name: attributeId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                  description: Attribute name
                type:
                  type: number
                  description: 'Attribute type:

                    0 -string

                    1 - number

                    2 - date

                    3 - link

                    4 - list

                    5 - multiList

                    '
                mandatory:
                  type: boolean
                  description: Is attribute required
                options:
                  type: array
                  description: Attribute options (only for "list" and "multiList" types
                order:
                  type: integer
                  description: Attribute order
                status:
                  type: integer
      responses:
        '200':
          description: Successfully
      operationId: updateBoardAttribute
      x-ai-role: crm_data_architect
      x-ai-description: Modifies the schema definition of a custom attribute on a CRM board. Attributes define the data model for board entities — changing a type (e.g., from string to list) affects how all existing contact/deal data stored under this attribute is interpreted. Order and mandatory flags control UI behavior and data entry validation across the board.
      x-ai-reasoning-instructions:
      - Before changing `type`, warn the user that existing data stored under this attribute may become incompatible or unreadable with the new type.
      - If `type` is set to 4 (list) or 5 (multiList), verify that `options` array is also provided — otherwise the attribute will be unusable.
      - If `mandatory` is set to true, existing board records without this attribute will fail validation on next update — inform the user about the impact.
      - Changing `order` repositions the attribute in the UI; use this to group related attributes visually.
      - Confirm that both `boardId` and `attributeId` exist before attempting the update to avoid misleading 404 errors.
      x-ai-responding-instructions:
      - Confirm which fields were updated and briefly describe the effect (e.g., 'Attribute is now required for all records').
      - If `type` was changed, proactively note potential data compatibility risks.
      - If `options` were updated for a list/multiList attribute, mention that removed options may affect existing records using those values.
      - Suggest verifying board records after structural changes to ensure data integrity.
      x-ai-suggestions:
      - Use `getBoardAttributes` to fetch current attribute config before patching.
      - After updating a mandatory attribute, review existing records for compliance.
      - Reorder attributes (`order` field) to improve data entry UX on the board UI.
      x-ai-capabilities:
        confirmation:
          type: Recommended
          message: Changing attribute type or mandatory status affects all existing board records. Confirm before proceeding.
        security_info:
          data_handling:
          - ResourceStateUpdate
          - SchemaModification
components:
  schemas:
    BoardAttribute:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: integer
        mandatory:
          type: boolean
        options:
          type: array
          default:
          - 1
          - 2
        status:
          type: integer
        order:
          type: integer
  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.

        '