Blackbaud Nameformatconfigurations API

openapi: 3.2.0
info:
  title: 'Blackbaud SKY API: Constituent Nameformatconfigurations API'
  description: This API manages constituent information and related entities such as addresses, phones, emails, and notes.
  version: '1.0'
  x-apievangelist-provenance:
    source: https://developer.sky.blackbaud.com/developer/apis/56b76470069a0509c8f1c5b3
    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/constituent/v1
security:
- Bb-Api-Subscription-Key: []
  OAuth2: []
tags:
- name: Nameformatconfigurations
paths:
  /nameformatconfigurations:
    get:
      operationId: ListNameFormatConfigurations
      summary: Name format configuration list
      description: Returns a list of all available name format configurations.
      parameters:
      - name: constituent_id
        in: query
        required: false
        schema:
          type: array
        description: The ID of the constituent to display the name format configurations in.
      - name: include_formula
        in: query
        required: false
        schema:
          type: boolean
        description: 'Whether to include the formula for each name format configuration. The formula is substantially

          larger than the rest of the entity, so it is omitted unless it is requested.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Represents the number of records to return. The default is 500. The maximum is 5000.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: Represents the number of records to skip. For use with pagination.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains a <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/constituent#Collection">collection</a> of <a href="https://developer.blackbaud.com/skyapi/api/entity-reference/constituent#NameFormatConfiguration">name format configuration</a> entities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCollectionOfNameFormatConfigurationRead'
              example:
                count: 45
                value:
                - id: '47'
                  format: '[Title 1] and [Spouse Title 1] [First Name] [Middle Name Initial] [Last Name] [Suffix 1]'
                  formatted_name: Dr. and Mrs. Robert C. Hernandez
                - id: '46'
                  format: '[Title 1] and [Spouse Title 1] [First Name] [Middle Name Initial] [Last Name]'
                  formatted_name: Dr. and Mrs. Robert C. Hernandez
                - id: '1'
                  format: '[Title 1] and [Spouse Title 1] [First Name] [Middle Name Initial] [Last Name] [Suffix 1] , Class of [Class Of]'
                  formatted_name: Dr. and Mrs. Robert C. Hernandez, Class of 1987
                - id: '2'
                  format: '[Title 1] [First Name] [Middle Name Initial] [Last Name] and↵*[Spouse Title 1] [Spouse First Name] [Spouse Middle Name Initial] [Spouse Last Name]'
                  formatted_name: Dr. Robert C. Hernandez and\ Mrs. Wendy Hernandez
                - id: '3'
                  format: '[Spouse Title 1] and [Title 1] [Spouse First Name] [Spouse Middle Name Initial] [Spouse Last Name] [Spouse Suffix 1]'
                  formatted_name: Mrs. and Dr. Wendy Hernandez
                - id: '4'
                  format: '[Spouse Title 1] [Spouse First Name] [Spouse Middle Name Initial] [Spouse Last Name] and↵*[Title 1] [First Name] [Middle Name Initial] [Last Name]'
                  formatted_name: Mrs. Wendy Hernandez and\ Dr. Robert C. Hernandez
                - id: '5'
                  format: '[Title 2] [First Name] and [Spouse First Name] [Last Name]'
                  formatted_name: Robert and Wendy Hernandez
                - id: '6'
                  format: '[Title 1] [First Name] [Middle Name Initial] [Last Name] [Suffix 1]'
                  formatted_name: Dr. Robert C. Hernandez
                - id: '7'
                  format: '[Title 1] [Title 2] [First Name] [Middle Name Initial] [Last Name] [Suffix 1]'
                  formatted_name: Dr. Robert C. Hernandez
                - id: '8'
                  format: '[First Name] [Middle Name Initial] [Last Name] [Suffix 1]'
                  formatted_name: Robert C. Hernandez
                - id: '9'
                  format: '[Last Name], [First Name] [Middle Name Initial]'
                  formatted_name: Hernandez, Robert C.
                - id: '10'
                  format: '[First Name] [Middle Name] [Last Name] [Suffix 1]'
                  formatted_name: Robert Carlos Hernandez
                - id: '11'
                  format: '[Spouse Title 1] [Spouse First Name] [Spouse Middle Name Initial] [Spouse Last Name] [Spouse Suffix 1]'
                  formatted_name: Mrs. Wendy Hernandez
                - id: '12'
                  format: '[Title 2] [Spouse First Name] [Spouse Middle Name Initial] [Spouse Last Name] [Spouse Suffix 1]'
                  formatted_name: Wendy Hernandez
                - id: '13'
                  format: '[Spouse Title 1] [First Name] [Middle Name Initial] [Last Name] [Suffix 1]'
                  formatted_name: Mrs. Robert C. Hernandez
                - id: '14'
                  format: '[Spouse Title 1] [Spouse First Name] [Spouse Last Name]-[Last Name]'
                  formatted_name: Mrs. Wendy Hernandez-Hernandez
                - id: '15'
                  format: '[Spouse First Name] [Spouse Middle Name Initial] [Spouse Last Name] [Spouse Suffix 1]'
                  formatted_name: Wendy Hernandez
                - id: '16'
                  format: '[Title 1] and [Spouse Title 1] [Last Name]'
                  formatted_name: Dr. and Mrs. Hernandez
                - id: '17'
                  format: '[Title 1] [Last Name] and [Spouse Title 1] [Spouse Last Name]'
                  formatted_name: Dr. Hernandez and Mrs. Hernandez
                - id: '18'
                  format: '[Title 1] [Last Name] and [Spouse Last Name]'
                  formatted_name: Dr. Hernandez and Hernandez
                - id: '19'
                  format: '[Spouse Title 1] and [Title 1] [Spouse Last Name]'
                  formatted_name: Mrs. and Dr. Hernandez
                - id: '20'
                  format: '[Spouse Title 1] [Spouse Last Name] and [Title 1] [Last Name]'
                  formatted_name: Mrs. Hernandez and Dr. Hernandez
                - id: '21'
                  format: '[Title 1] [Last Name]'
                  formatted_name: Dr. Hernandez
                - id: '22'
                  format: '[Title 2] [Last Name]'
                  formatted_name: Hernandez
                - id: '23'
                  format: '[Title 1] [Former Name]-[Last Name]'
                  formatted_name: Dr.-Hernandez
                - id: '24'
                  format: '[Spouse Title 1] [Spouse Last Name]'
                  formatted_name: Mrs. Hernandez
                - id: '25'
                  format: '[Spouse Title 2] [Spouse Last Name]'
                  formatted_name: Hernandez
                - id: '26'
                  format: '[Spouse Title 1] [Last Name]'
                  formatted_name: Mrs. Hernandez
                - id: '27'
                  format: '[Spouse Title 1] [Spouse Middle Name]-[Spouse Last Name]'
                  formatted_name: Mrs.-Hernandez
                - id: '28'
                  format: '[First Name] and [Spouse First Name]'
                  formatted_name: Robert and Wendy
                - id: '29'
                  format: '[Spouse First Name] and [First Name]'
                  formatted_name: Wendy and Robert
                - id: '30'
                  format: '[First Name] and [Spouse Nickname]'
                  formatted_name: Robert
                - id: '31'
                  format: '[Spouse Nickname] and [First Name]'
                  formatted_name: and Robert
                - id: '32'
                  format: '[Spouse First Name] and [Nickname]'
                  formatted_name: Wendy and Bob
                - id: '33'
                  format: '[Nickname] and [Spouse First Name]'
                  formatted_name: Bob and Wendy
                - id: '34'
                  format: '[First Name]'
                  formatted_name: Robert
                - id: '35'
                  format: '[Nickname]'
                  formatted_name: Bob
                - id: '36'
                  format: '[Middle Name]'
                  formatted_name: Carlos
                - id: '37'
                  format: '[Spouse First Name]'
                  formatted_name: Wendy
                - id: '38'
                  format: '[Spouse Nickname]'
                - id: '39'
                  format: '[Spouse Middle Name]'
                - id: '42'
                  format: '[Organization Name]'
                  formatted_name: Davis & Johnson Pharmaceuticals
                - id: '43'
                  format: '[Title 1]'
                  formatted_name: Dr.
                - id: '44'
                  format: Friend
                  formatted_name: Friend
                - id: '45'
                  format: '[Title 1] [First Name] [Last Name] and Guest'
                  formatted_name: Dr. Robert Hernandez and Guest
        '403':
          description: Returned when the user does not have permission to view the name format configurations.
      tags:
      - Nameformatconfigurations
components:
  schemas:
    NameFormatFormulaFieldRead:
      description: 'A single field within a name format configuration''s formula. The order of the fields within the

        formula is significant.'
      type: object
      properties:
        field_id:
          description: The identifier of the name field that this formula field substitutes.
          type: string
        field_name:
          description: 'The name of the field, such as "[Spouse First Name]". For a field whose type is "Custom", this

            is the literal text that the organization typed into the formula, such as a connector like "and".'
          type: string
        field_type:
          description: The type of the field.
          enum:
          - Custom
          - Bio
          - Spouse
          - ConstitAddrsSal
          - ConstituencyAbbrev
          - Constituency
          - MembershipCat
          - ClassOf
          - SpouseClassOf
          - OrganizationName
          - ConstituentId
          - Contact
          - Deceased
          - ProspectClassification
          - ProspectStatus
          type: string
        sequence:
          format: int32
          description: The sequence of the field within the name format configuration.
          type: integer
        is_initial:
          description: Whether to render the field as an initial rather than in full.
          type: boolean
        is_after_comma:
          description: Whether to precede the field with a comma and a space.
          type: boolean
        is_before_line_break_when_space_is_limited:
          description: Whether to insert a line break after the field when the available space is limited.
          type: boolean
        is_before_line_break:
          description: Whether to always insert a line break after the field.
          type: boolean
        is_concatenated_with_next_name_field:
          description: Whether to omit the separating space between the field and the field that follows it.
          type: boolean
        is_required_for_preceding_custom_field:
          description: 'Whether the field is required for the custom field that precedes it. When the field is empty, it

            is omitted along with that preceding custom field, so that a conditional portion of the name and

            the connector that introduces it are dropped together.'
          type: boolean
      x-display-name: Name format formula field
      x-display-id: NameFormatFormulaField
    ApiCollectionOfNameFormatConfigurationRead:
      description: Fetching data all at once quickly becomes unmanageable. The collection entity helps by returning paginated chunks of large data sets. This entity includes helpful metadata and properties to paginate and iterate through the data.
      type: object
      properties:
        count:
          format: int32
          description: The number of items available for retrieval into the collection after applying any request parameters. The <b>limit</b> and <b>offset</b> parameters do not affect the <b>count</b>, but to facilitate paging, they may affect the number of items in the <b>value</b> result set.
          type: integer
        next_link:
          description: For paginated responses, the URI for the next page of results.
          type: string
        value:
          description: The set of items included in the response. This may be a subset of the items in the collection.
          type: array
          items:
            $ref: '#/components/schemas/NameFormatConfigurationRead'
      x-hidden: true
      x-base-type: '#/definitions/ApiCollection'
    NameFormatConfigurationRead:
      description: Name format configurations provide a preset layout to display a constituent's name.
      type: object
      properties:
        id:
          description: The name format configuration identifier.
          type: string
        format:
          description: The name format.
          type: string
        formatted_name:
          description: The preview of the format applied to the given constituent's name.
          type: string
        formula:
          description: 'The ordered list of fields that make up the name format. Unlike format, which is the

            formula rendered as an example, this describes how each field is rendered. Only included when

            the include_formula parameter is set to true.'
          type: array
          items:
            $ref: '#/components/schemas/NameFormatFormulaFieldRead'
      x-display-name: Name format configuration
      x-display-id: NameFormatConfiguration
  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: {}