Blackbaud Customfieldcategories API

openapi: 3.2.0
info:
  title: 'Blackbaud SKY API: Custom field Customfieldcategories API'
  description: This API supports managing custom field categories.
  version: '1.0'
  x-apievangelist-provenance:
    source: https://developer.sky.blackbaud.com/developer/apis/customfield
    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/customfield
security:
- Bb-Api-Subscription-Key: []
  OAuth2: []
tags:
- name: Customfieldcategories
paths:
  /customfieldcategories:
    post:
      operationId: AddCustomFieldCategory
      summary: Add custom field category (PREVIEW)
      description: 'Add custom field category.


        ***This endpoint is in PREVIEW and may be changed or removed at any time.***'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldCategoryAdd'
            example:
              record_type: Constituent
              description: Alternate constituent code
              type_of_data: Table
              code_table_id: 43
              required: true
              must_be_unique: true
              sequence: 1
              inactive: false
        description: Custom field category add
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
              example:
                id: '2'
        '400':
          description: Returned when the request is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CustomFieldsErrorCodes'
              example:
                type: urn:blackbaud:unique-description
                title: One or more validation errors occurred.
                status: 400
                detail: Custom field category must be unique.
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
      tags:
      - Customfieldcategories
    get:
      operationId: GetCustomFieldCategories
      summary: Get custom field categories (PREVIEW)
      description: 'Gets a list of custom field categories for a given custom field type.


        ***This endpoint is in PREVIEW and may be changed or removed at any time.***'
      parameters:
      - name: record_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - Constituent
          - Gift
          - Action
          - Education
          - Event
          - Participant
          - Campaign
          - Appeal
          - Fund
          - Package
          - Address
          - Job
          - Membership
          - IndividualRelationship
          - OrganizationRelationship
          - Financial
          - Opportunity
        description: The record type to filter custom field categories by.
      - name: search_text
        in: query
        required: false
        schema:
          type: string
        description: Fuzzy search for custom field categories by description.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: '50'
        description: The maximum number of records to return. Defaults to 50, maximum 200.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: The number of records to skip, for use with pagination.
      - name: include_inactive
        in: query
        required: false
        schema:
          type: boolean
        description: Include inactive custom field categories in the results.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomFieldCategoriesResponse'
              example:
                custom_field_categories:
                - custom_field_category_id: 1
                  description: Origin
                  type_of_data: Text
                  required: false
                  inactive: false
                  code_table_id: 1
                  must_be_unique: false
                  has_values: false
                count: 1
                limit: 10
                offset: 0
      tags:
      - Customfieldcategories
  /customfieldcategories/{id}:
    delete:
      operationId: DeleteCustomField
      summary: Delete custom field (PREVIEW)
      description: 'Delete a custom field by ID.


        ***This endpoint is in PREVIEW and may be changed or removed at any time.***'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Custom field category ID
      - name: record_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - Constituent
          - Gift
          - Action
          - Education
          - Event
          - Participant
          - Campaign
          - Appeal
          - Fund
          - Package
          - Address
          - Job
          - Membership
          - IndividualRelationship
          - OrganizationRelationship
          - Financial
          - Opportunity
        description: Custom field record type
      responses:
        '200':
          description: OK
      tags:
      - Customfieldcategories
    patch:
      operationId: EditCustomFieldCategory
      summary: Edit custom field category (PREVIEW)
      description: 'Edit custom field category.


        ***This endpoint is in PREVIEW and may be changed or removed at any time.***'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the custom field category to edit.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldCategoryEdit'
            example:
              record_type: Constituent
              description: Alternate constituent code
              type_of_data: Table
              code_table_id: 43
              required: true
              must_be_unique: true
              sequence: 1
              inactive: false
        description: Custom field category edit
      responses:
        '200':
          description: OK
        '400':
          description: Returned when the request is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CustomFieldsErrorCodes'
              example:
                type: urn:blackbaud:unique-description
                title: One or more validation errors occurred.
                status: 400
                detail: Custom field category must be unique.
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
      tags:
      - Customfieldcategories
    get:
      operationId: GetCustomFieldCategoryById
      summary: Get custom field category by ID (PREVIEW)
      description: 'Gets custom field category by ID.


        ***This endpoint is in PREVIEW and may be changed or removed at any time.***'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Custom field category ID
      - name: record_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - Constituent
          - Gift
          - Action
          - Education
          - Event
          - Participant
          - Campaign
          - Appeal
          - Fund
          - Package
          - Address
          - Job
          - Membership
          - IndividualRelationship
          - OrganizationRelationship
          - Financial
          - Opportunity
        description: Custom field record type
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldCategory'
              example:
                custom_field_category_id: 1
                description: Description
                type_of_data: Text
                required: false
                inactive: true
                must_be_unique: false
                has_values: false
      tags:
      - Customfieldcategories
components:
  schemas:
    CustomFieldCategory:
      type: object
      properties:
        custom_field_category_id:
          type: integer
          description: ID of the custom field category.
          format: int32
        description:
          type:
          - string
          - 'null'
          description: The custom field category's description.
        type_of_data:
          $ref: '#/components/schemas/CustomFieldTypeOfData'
        required:
          type: boolean
          description: The required flag for the custom field category.
        inactive:
          type: boolean
          description: Whether the custom field category is active or inactive.
        code_table_id:
          type:
          - integer
          - 'null'
          description: ID of the code table for categories of type Blackbaud.Renxt.CustomFields.Service.Models.Enums.CustomFieldTypeOfData.Table.
          format: int32
        code_table_name:
          type:
          - string
          - 'null'
          description: Name of the code table corresponding to Blackbaud.Renxt.CustomFields.Service.Models.CustomFieldCategory.CodeTableId.
        must_be_unique:
          type: boolean
          description: Indicates if the custom field category values must be unique.
        sequence:
          type:
          - integer
          - 'null'
          description: Sequence of the custom field category.
          format: int32
        has_values:
          type: boolean
          description: Indicates when the custom field category is in use with a value on one or more records that it applies to.
      additionalProperties: false
      description: Custom field category model
    CustomFieldsRecordType:
      enum:
      - Constituent
      - Gift
      - Action
      - Education
      - Event
      - Participant
      - Campaign
      - Appeal
      - Fund
      - Package
      - Address
      - Job
      - Membership
      - IndividualRelationship
      - OrganizationRelationship
      - Financial
      - Opportunity
      type: string
      description: Custom fields record type<p>Members:</p><ul><li><i>Constituent</i> - Constituent</li><li><i>Gift</i> - Gift</li><li><i>Action</i> - Action</li><li><i>Education</i> - Education</li><li><i>Event</i> - Event</li><li><i>Participant</i> - Participant</li><li><i>Campaign</i> - Campaign</li><li><i>Appeal</i> - Appeal</li><li><i>Fund</i> - Fund</li><li><i>Package</i> - Package</li><li><i>Address</i> - Address</li><li><i>Job</i> - Job</li><li><i>Membership</i> - Membership</li><li><i>IndividualRelationship</i> - Individual relationship</li><li><i>OrganizationRelationship</i> - Organization relationship</li><li><i>Financial</i> - Financial</li><li><i>Opportunity</i> - Opportunity</li></ul>
    GetCustomFieldCategoriesResponse:
      required:
      - limit
      - offset
      type: object
      properties:
        custom_field_categories:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CustomFieldCategory'
          description: The list of custom field categories.
        count:
          type: integer
          description: The total number of items in the collection before limit/offset.
          format: int32
        limit:
          type: integer
          description: The limit on the list request.
          format: int32
        offset:
          type: integer
          description: The offset on the list request.
          format: int32
      additionalProperties: false
      description: Response model for GET /customfieldcategories
      x-bb-suppressions:
      - list_operation_pagination_style
    CustomFieldTypeOfData:
      enum:
      - Text
      - Number
      - Date
      - Currency
      - Boolean
      - Table
      - Constituent
      - FuzzyDate
      type: string
      description: The different types of data that can be stored in a custom field.<p>Members:</p><ul><li><i>Text</i> - Text field</li><li><i>Number</i> - Numeric field</li><li><i>Date</i> - Full date field</li><li><i>Currency</i> - Currency field</li><li><i>Boolean</i> - Yes/no field</li><li><i>Table</i> - Code table entry field</li><li><i>Constituent</i> - Specific constituent record field</li><li><i>FuzzyDate</i> - Fuzzy date field</li></ul>
    CustomFieldCategoryAdd:
      required:
      - description
      - record_type
      type: object
      properties:
        record_type:
          $ref: '#/components/schemas/CustomFieldsRecordType'
        description:
          minLength: 1
          type: string
          description: Custom field category name.
        type_of_data:
          $ref: '#/components/schemas/CustomFieldTypeOfData'
        code_table_id:
          type:
          - integer
          - 'null'
          description: The code table ID, used for table type custom fields.
          format: int32
        required:
          type: boolean
          description: Whether the custom field is required for all records of the given type.
        must_be_unique:
          type: boolean
          description: Whether the category values must be unique.
        sequence:
          type:
          - integer
          - 'null'
          description: The sequence, controlling the order of the category in the categories list.
          format: int32
        inactive:
          type: boolean
          description: Whether the custom field category is active or inactive.
      additionalProperties: false
      description: Model of a custom field category to be added.
    PostResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The identifier of the resulting record
      additionalProperties: false
      description: Response object for POST requests
    CustomFieldsErrorCodes:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".<br/><br/>Available values:<table><tr><th>type</th><th>detail</th></tr><tr><td>urn:blackbaud:model-validation-error</td><td>A model validation rule was violated, such as a missing required field.</td></tr><tr><td>urn:blackbaud:custom-field-category-description-must-be-unique</td><td>Custom field category description must be unique for the record type.</td></tr><tr><td>urn:blackbaud:description-too-long</td><td>The description must be 50 characters or less.</td></tr><tr><td>urn:blackbaud:required-field</td><td>The required field '{0}' does not have a value.</td></tr><tr><td>urn:blackbaud:invalid-value</td><td>'{0}' is not a valid value for {1}.</td></tr></table>
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
      x-bb-error-types:
      - urn:blackbaud:model-validation-error
      - urn:blackbaud:custom-field-category-description-must-be-unique
      - urn:blackbaud:description-too-long
      - urn:blackbaud:required-field
      - urn:blackbaud:invalid-value
    CustomFieldCategoryEdit:
      required:
      - description
      - record_type
      type: object
      properties:
        record_type:
          $ref: '#/components/schemas/CustomFieldsRecordType'
        description:
          minLength: 1
          type: string
          description: Custom field category name.
        type_of_data:
          $ref: '#/components/schemas/CustomFieldTypeOfData'
        code_table_id:
          type:
          - integer
          - 'null'
          description: The code table ID, used for table type custom fields.
          format: int32
        required:
          type: boolean
          description: Whether the custom field is required for all records of the given type.
        must_be_unique:
          type: boolean
          description: Whether the category values must be unique.
        sequence:
          type:
          - integer
          - 'null'
          description: The sequence, controlling the order of the category in the categories list.
          format: int32
        inactive:
          type: boolean
          description: Whether the custom field category is active or inactive.
      additionalProperties: false
      description: Model of a custom field category to be edited.
  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: {}