Blackbaud Consent API

openapi: 3.2.0
info:
  title: 'Blackbaud SKY API: Communication Preference Consent API'
  description: This API manages constituent communication preference information and related entities such as constituent consent.
  version: '1.0'
  x-apievangelist-provenance:
    source: https://developer.sky.blackbaud.com/developer/apis/communication-preference
    method: assembled from Blackbaud's public API Management developer data API (operations, parameters, representations, examples, stored definitions); nothing authored
    assembled: '2026-10-14'
servers:
- url: https://api.sky.blackbaud.com/commpref
security:
- Bb-Api-Subscription-Key: []
  OAuth2: []
tags:
- name: Consent
paths:
  /v1/consent/categories:
    get:
      operationId: ListConsentCategories
      summary: Consent categories
      description: Returns a list of consent categories.
      parameters:
      - name: include_inactive
        in: query
        required: false
        schema:
          type: boolean
        description: Set this parameter to "true" to include inactive results in the response.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains a <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentCategoryCollection">collection</a> of <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentCategory">consent categories</a>.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentCategoryCollection'
              example:
                count: 3
                value:
                - description: Fundraising
                  inactive: false
                  sequence: 1
                - description: Advocacy
                  inactive: true
                  sequence: 2
                - description: Newsletters
                  sequence: 7
      tags:
      - Consent
  /v1/consent/channelcategories:
    get:
      operationId: ListConsentChannelCategories
      summary: Consent channel categories
      description: Returns a list of valid consent channel category combinations.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains a <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentChannelCategoryCollection">collection</a> of <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentChannelCategory">consent channel category combinations</a>.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentChannelCategoryCollection'
              example:
                count: 3
                value:
                - channel: Email
                  category: Newsletter
                  sequence: 1
                - channel: Email
                  sequence: 2
                - channel: Phone
                  sequence: 3
      tags:
      - Consent
  /v1/consent/channels:
    get:
      operationId: ListConsentChannels
      summary: Consent channels
      description: Returns a list of consent channels.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains a <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentChannelCollection">collection</a> of <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentChannel">consent channels</a>.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentChannelCollection'
              example:
                count: 2
                value:
                - description: Email
                - description: Phone
      tags:
      - Consent
  /v1/consent/consents:
    post:
      operationId: CreateConstituentConsent
      summary: Constituent consent (Create)
      description: Creates a consent record for a constituent.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConstituentConsentAdd'
            example:
              constituent_id: '280'
              channel: Email
              category: Fundraising
              source: Web form
              consent_date: '2018-07-30T23:04:52Z'
              constituent_consent_response: OptIn
              privacy_notice: Sample privacy notice
              consent_statement: Sample consent statement
        description: The constituent's consent record.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains the ID of the new consent record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
              example:
                id: '4343'
        '400':
          description: Returned when the request body is not in the appropriate format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ConsentConsentsPost400ApplicationJsonResponse'
              example:
              - message: The request body is not in the appropriate format.
                error_name: BadRequest
                error_code: 400
                raw_message: The request body is not in the appropriate format.
        '403':
          description: Returned when the user does not have permission to create a consent record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ConsentConsentsPost403ApplicationJsonResponse'
              example:
              - message: The user does not have permission to create a record.
                error_name: Forbidden
                error_code: 403
                raw_message: The user does not have permission to create a record.
        '404':
          description: Returned when the specified constituent cannot be found or when the provided channel, category, or source cannot be resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ConsentConsentsPost404ApplicationJsonResponse'
              example:
              - message: The requested record was not found.
                error_name: NotFound
                error_code: 404
                raw_message: The requested record was not found.
      tags:
      - Consent
  /v1/consent/sources:
    get:
      operationId: ListConsentSources
      summary: Consent sources
      description: Returns a list of consent sources.
      parameters:
      - name: include_inactive
        in: query
        required: false
        schema:
          type: boolean
        description: Set this parameter to "true" to include inactive results in the response.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains a <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentSourceCollection">collection</a> of <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/communication-preference#ConsentSource">consent sources</a>.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentSourceCollection'
              example:
                count: 3
                value:
                - description: Web form
                  inactive: false
                  sequence: 1
                - description: Phone call inbound
                  inactive: true
                  sequence: 2
                - description: Mail response
                  sequence: 7
      tags:
      - Consent
components:
  schemas:
    V1ConsentConsentsPost403ApplicationJsonResponse:
      type: array
      items:
        $ref: '#/components/schemas/ServiceError'
      x-apim-inline: true
    ConsentChannelCategory:
      type: object
      properties:
        channel:
          type:
          - string
          - 'null'
          description: The name of the channel included in the channel/category combination.
        category:
          type:
          - string
          - 'null'
          description: The name of the category included in the channel/category combination.
        sequence:
          type:
          - integer
          - 'null'
          description: The placement of the channel/category in the order of channel/category table values, if defined.
          format: int32
      additionalProperties: false
      description: Represents a valid consent channel category combination.
    ConsentSource:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: The name of the consent source.
        inactive:
          type:
          - boolean
          - 'null'
          description: Indicates whether the consent source is inactive.
        sequence:
          type:
          - integer
          - 'null'
          description: The placement of the source in the order of source table values, if defined.
          format: int32
      additionalProperties: false
      description: Represents the consent source entity.
    ConsentCategoryCollection:
      type: object
      properties:
        count:
          type: integer
          description: The number of consent categories in the list.
          format: int32
          readOnly: true
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ConsentCategory'
          description: The set of consent categories included in the response.
      additionalProperties: false
      description: A collection of consent categories.
    ConstituentConsentAdd:
      required:
      - channel
      - consent_date
      - constituent_consent_response
      - constituent_id
      type: object
      properties:
        constituent_id:
          type: string
          description: The immutable system record ID of the constituent associated with the consent record.
        channel:
          type: string
          description: The channel that the consent response applies to. Available values can be obtained from the <a href="https://developer.sky.blackbaud.com/docs/services/communication-preference/operations/ListConsentChannels">Consent Channels List</a>.
        category:
          type:
          - string
          - 'null'
          description: The category that the consent response applies to. Available values can be obtained from the <a href="https://developer.sky.blackbaud.com/docs/services/communication-preference/operations/ListConsentCategories">Consent Categories List</a>.
        source:
          type:
          - string
          - 'null'
          description: The source of the consent response from the constituent. Available values can be obtained from the <a href="https://developer.sky.blackbaud.com/docs/services/communication-preference/operations/ListConsentSources">Consent Sources List</a>.
        consent_date:
          type: string
          description: The date the consent response was received.
          format: date-time
        constituent_consent_response:
          title: ConstituentConsentResponse
          enum:
          - OptIn
          - OptOut
          - NoResponse
          type: string
          description: How the constituent responded to consent for the specified channel/category. Available values are <i>OptIn</i>, <i>OptOut</i>, and <i>NoResponse</i>.
        privacy_notice:
          maxLength: 7999
          type:
          - string
          - 'null'
          description: The privacy notice provided to the constituent.
        consent_statement:
          maxLength: 7999
          type:
          - string
          - 'null'
          description: The statement the constituent responded to when providing consent.
        user_name:
          maxLength: 255
          type:
          - string
          - 'null'
          description: The user name associated with the consent. If not supplied, will have a default set based on the user's account.
      additionalProperties: false
      description: Represents the consent entity to add to the specified constituent.
    ConsentChannelCollection:
      type: object
      properties:
        count:
          type: integer
          description: The number of consent channels in the list.
          format: int32
          readOnly: true
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ConsentChannel'
          description: The set of consent channels included in the response.
      additionalProperties: false
      description: A collection of consent channels.
    ServiceError:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
          description: The message of the service error with any string arguments replaced.
        error_name:
          type:
          - string
          - 'null'
          description: The name of the service error.
        error_code:
          type: integer
          description: Code number of the service error.
          format: int32
        raw_message:
          type:
          - string
          - 'null'
          description: 'The raw message of the service error. This message may contain string replacement arguments (ie: {0}, {1}, etc) that map to the ''error_args'' property and will be replaced when you get the full message from the ''message'' property.'
        error_args:
          type:
          - array
          - 'null'
          items:
            type: string
          description: A list of arguments to be replaced in the raw message. Useful for when the message needs to be localized.
      additionalProperties: false
      description: Base service error contract.
    V1ConsentConsentsPost400ApplicationJsonResponse:
      type: array
      items:
        $ref: '#/components/schemas/ServiceError'
      x-apim-inline: true
    ConsentSourceCollection:
      type: object
      properties:
        count:
          type: integer
          description: The number of consent sources in the list.
          format: int32
          readOnly: true
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ConsentSource'
          description: The set of consent sources included in the response.
      additionalProperties: false
      description: A collection of consent sources.
    ConsentChannelCategoryCollection:
      type: object
      properties:
        count:
          type: integer
          description: The number of consent channel categories in the list.
          format: int32
          readOnly: true
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ConsentChannelCategory'
          description: The set of consent channel categories included in the response.
      additionalProperties: false
      description: A collection of consent channel categories.
    ConsentCategory:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: The name of the consent category.
        inactive:
          type:
          - boolean
          - 'null'
          description: Indicates whether the consent category is inactive.
        sequence:
          type:
          - integer
          - 'null'
          description: The placement of the category in the order of category table values, if defined.
          format: int32
      additionalProperties: false
      description: Represents the consent category entity.
    PostResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Id of the created record.
      additionalProperties: false
      description: Response for creating a record.
    ConsentChannel:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: The name of the consent channel.
      additionalProperties: false
      description: Represents the consent channel entity.
    V1ConsentConsentsPost404ApplicationJsonResponse:
      type: array
      items:
        $ref: '#/components/schemas/ServiceError'
      x-apim-inline: true
  securitySchemes:
    Bb-Api-Subscription-Key:
      type: apiKey
      name: Bb-Api-Subscription-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.blackbaud.com/oauth/authorize
          tokenUrl: https://oauth2.sky.blackbaud.com/token
          scopes: {}