openapi: 3.2.0
info:
  title: Contact Management Consent Groups API
  version: 1.0.0
servers:
- url: https://api.brevo.com/v3
  description: https://api.brevo.com/v3
tags:
- name: consentGroups
paths:
  /contacts/consent-groups:
    get:
      operationId: getConsentGroups
      summary: List all consent groups
      description: 'Returns a paginated list of consent groups for the account.


        <Note>This endpoint is only available when the Consent Groups feature is enabled for your account. Returns `403` if the feature is not activated.</Note>'
      tags:
      - consentGroups
      parameters:
      - name: limit
        in: query
        description: Maximum number of results to return (default 10, max 50)
        required: false
        schema:
          type: integer
          format: int64
          default: 10
      - name: offset
        in: query
        description: Number of results to skip (default 0)
        required: false
        schema:
          type: integer
          format: int64
          default: 0
      - name: id
        in: query
        description: Filter by consent group ID
        required: false
        schema:
          type: integer
          format: int64
      - name: name
        in: query
        description: Filter by name (case-insensitive partial match)
        required: false
        schema:
          type: string
      - name: signupMode
        in: query
        description: Filter by signup mode
        required: false
        schema:
          $ref: '#/components/schemas/ContactsConsentGroupsGetParametersSignupMode'
      - name: api-key
        in: header
        description: The API key should be passed in the request headers as `api-key` for authentication.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of consent groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentGroupsListResponse'
        '400':
          description: 'Bad request. Possible error codes: `INVALID_ID` (invalid id filter value), `INVALID_SIGNUP_MODE` (invalid signupMode value).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '403':
          description: 'Consent Groups feature not enabled for this account. Error code: `CONSENT_GROUP_NOT_ENABLED`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
    post:
      operationId: createConsentGroup
      summary: Create a consent group
      description: 'Creates a new consent group for the account.


        <Note>This endpoint is only available when the Consent Groups feature is enabled for your account.</Note>'
      tags:
      - consentGroups
      parameters:
      - name: api-key
        in: header
        description: The API key should be passed in the request headers as `api-key` for authentication.
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Consent group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentGroup'
        '400':
          description: 'Bad request. Possible error codes: `MISSING_REQUIRED_FIELD` (name or signupMode missing), `INVALID_SIGNUP_MODE` (invalid signupMode value), `FIELD_TOO_LONG` (name exceeds 255 or description exceeds 500 characters), `INVALID_LIST_ID` (one or more listIds are invalid).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '403':
          description: 'Consent Groups feature not enabled for this account. Error code: `CONSENT_GROUP_NOT_ENABLED`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '409':
          description: 'A consent group with this name already exists. Error code: `NAME_ALREADY_EXISTS`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConsentGroupRequest'
  /contacts/consent-groups/{id}:
    get:
      operationId: getConsentGroup
      summary: Get a consent group
      description: 'Returns a single consent group by ID for the account.


        <Note>This endpoint is only available when the Consent Groups feature is enabled for your account.</Note>'
      tags:
      - consentGroups
      parameters:
      - name: id
        in: path
        description: ID of the consent group
        required: true
        schema:
          type: integer
          format: int64
      - name: api-key
        in: header
        description: The API key should be passed in the request headers as `api-key` for authentication.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Consent group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentGroup'
        '400':
          description: 'Bad request. Error code: `INVALID_ID` (id must be a positive integer).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '403':
          description: 'Consent Groups feature not enabled for this account. Error code: `CONSENT_GROUP_NOT_ENABLED`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '404':
          description: 'Consent group not found. Error code: `CONSENT_GROUP_NOT_FOUND`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
    put:
      operationId: updateConsentGroup
      summary: Update a consent group
      description: 'Updates name, description, or signupMode of a consent group. At least one field must be provided.


        <Note>This endpoint is only available when the Consent Groups feature is enabled for your account.</Note>'
      tags:
      - consentGroups
      parameters:
      - name: id
        in: path
        description: ID of the consent group to update
        required: true
        schema:
          type: integer
          format: int64
      - name: api-key
        in: header
        description: The API key should be passed in the request headers as `api-key` for authentication.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated consent group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentGroup'
        '400':
          description: 'Bad request. Possible error codes: `INVALID_ID` (id must be a positive integer), `NO_FIELDS_TO_UPDATE` (no fields provided in request body), `INVALID_SIGNUP_MODE` (invalid signupMode value), `FIELD_TOO_LONG` (name exceeds 255 or description exceeds 500 characters).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '403':
          description: 'Consent Groups feature not enabled for this account. Error code: `CONSENT_GROUP_NOT_ENABLED`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '404':
          description: 'Consent group not found. Error code: `CONSENT_GROUP_NOT_FOUND`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '409':
          description: 'A consent group with this name already exists. Error code: `NAME_ALREADY_EXISTS`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConsentGroupRequest'
    delete:
      operationId: deleteConsentGroup
      summary: Delete a consent group
      description: 'Deletes a consent group by ID and removes it from all associated contacts.


        <Note>This endpoint is only available when the Consent Groups feature is enabled for your account.</Note>'
      tags:
      - consentGroups
      parameters:
      - name: id
        in: path
        description: ID of the consent group to delete
        required: true
        schema:
          type: integer
          format: int64
      - name: api-key
        in: header
        description: The API key should be passed in the request headers as `api-key` for authentication.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Consent group deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: 'Bad request. Error code: `INVALID_ID` (id must be a positive integer).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '403':
          description: 'Consent Groups feature not enabled for this account. Error code: `CONSENT_GROUP_NOT_ENABLED`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '404':
          description: 'Consent group not found. Error code: `CONSENT_GROUP_NOT_FOUND`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
components:
  schemas:
    ContactsConsentGroupsGetParametersSignupMode:
      type: string
      enum:
      - manual
      - automatic
      title: ContactsConsentGroupsGetParametersSignupMode
    ConsentGroupsListResponse:
      type: object
      properties:
        consentGroups:
          type: array
          items:
            $ref: '#/components/schemas/ConsentGroup'
          description: List of consent groups matching the filter
        total:
          type: integer
          format: int64
          description: Total number of consent groups matching the filter
        limit:
          type: integer
          format: int64
          description: Maximum number of results returned
        offset:
          type: integer
          format: int64
          description: Number of results skipped
      required:
      - consentGroups
      - total
      - limit
      - offset
      description: Paginated list of consent groups.
      title: ConsentGroupsListResponse
    ConsentGroup:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the consent group
        name:
          type: string
          description: Display name of the consent group
        description:
          type: string
          description: Optional description of the consent group
        signupMode:
          $ref: '#/components/schemas/ConsentGroupSignupMode'
          description: Controls how contacts are added to the group. `manual` — contacts are added explicitly via the API. `automatic` — contacts are added automatically at signup.
        contactsCount:
          type: integer
          format: int64
          description: Number of contacts currently in this consent group
        isDefault:
          type: boolean
          description: Whether this is a system-created default consent group
        createdAt:
          type: string
          format: date-time
          description: UTC date-time when the consent group was created (YYYY-MM-DDTHH:mm:ss.SSSZ)
        updatedAt:
          type: string
          format: date-time
          description: UTC date-time when the consent group was last updated (YYYY-MM-DDTHH:mm:ss.SSSZ)
      required:
      - id
      - name
      - signupMode
      - contactsCount
      - isDefault
      - createdAt
      - updatedAt
      description: A consent group representing a category of contact opt-in/opt-out preferences.
      title: ConsentGroup
    UpdateConsentGroupRequest:
      type: object
      properties:
        name:
          type: string
          description: New name for the consent group (max 255 characters)
        description:
          type: string
          description: New description (max 500 characters)
        signupMode:
          $ref: '#/components/schemas/UpdateConsentGroupRequestSignupMode'
          description: New signup mode
      description: Request body for updating a consent group. At least one field must be provided.
      title: UpdateConsentGroupRequest
    UpdateConsentGroupRequestSignupMode:
      type: string
      enum:
      - manual
      - automatic
      description: New signup mode
      title: UpdateConsentGroupRequestSignupMode
    errorModel:
      type: object
      properties:
        code:
          type: string
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - message
      title: errorModel
    ConsentGroupSignupMode:
      type: string
      enum:
      - manual
      - automatic
      description: Controls how contacts are added to the group. `manual` — contacts are added explicitly via the API. `automatic` — contacts are added automatically at signup.
      title: ConsentGroupSignupMode
    CreateConsentGroupRequestSignupMode:
      type: string
      enum:
      - manual
      - automatic
      description: Controls how contacts are added to the group. `manual` — contacts are added explicitly via the API. `automatic` — contacts are added automatically at signup.
      title: CreateConsentGroupRequestSignupMode
    CreateConsentGroupRequest:
      type: object
      properties:
        name:
          type: string
          description: Unique name for the consent group (max 255 characters)
        description:
          type: string
          description: Optional description (max 500 characters)
        signupMode:
          $ref: '#/components/schemas/CreateConsentGroupRequestSignupMode'
          description: Controls how contacts are added to the group. `manual` — contacts are added explicitly via the API. `automatic` — contacts are added automatically at signup.
        listIds:
          type: array
          items:
            type: integer
            format: int64
          description: Optional list of contact list IDs. Contacts from these lists will be copied once into this consent group at creation time.
      required:
      - name
      - signupMode
      description: Request body for creating a consent group.
      title: CreateConsentGroupRequest
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key
      description: The API key should be passed in the request headers as `api-key` for authentication.