openapi: 3.1.0
info:
  title: Brevo Contacts Agent Status Contact Lists API
  description: The Brevo Contacts API provides programmatic access to contact management features including creating, updating, and deleting contacts. Developers can organize contacts into lists, apply attributes and tags, import contacts in bulk, and build audience segments for targeted campaigns. The API also supports managing folders, contact attributes, and custom fields to structure contact data according to business needs.
  version: '3.0'
  contact:
    name: Brevo Support
    url: https://help.brevo.com
  termsOfService: https://www.brevo.com/legal/termsofuse/
servers:
- url: https://api.brevo.com/v3
  description: Brevo Production API Server
security:
- apiKeyAuth: []
tags:
- name: Contact Lists
  description: Manage contact lists for organizing and segmenting audiences.
paths:
  /contacts/lists:
    get:
      operationId: listContactLists
      summary: Get all contact lists
      description: Retrieves all contact lists in the account with their subscriber counts and folder assignments.
      tags:
      - Contact Lists
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: sort
        in: query
        description: Sort direction for the results.
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Contact lists retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListCollection'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createContactList
      summary: Create a contact list
      description: Creates a new contact list within a specified folder. Lists are used to organize contacts for targeted campaign sending.
      tags:
      - Contact Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactList'
      responses:
        '201':
          description: List created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    description: Unique identifier of the newly created list.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /contacts/lists/{listId}:
    get:
      operationId: getContactList
      summary: Get a contact list
      description: Retrieves the details of a specific contact list including subscriber count and configuration.
      tags:
      - Contact Lists
      parameters:
      - $ref: '#/components/parameters/listIdParam'
      responses:
        '200':
          description: Contact list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateContactList
      summary: Update a contact list
      description: Updates the name or folder assignment of an existing contact list.
      tags:
      - Contact Lists
      parameters:
      - $ref: '#/components/parameters/listIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactList'
      responses:
        '204':
          description: List updated successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteContactList
      summary: Delete a contact list
      description: Permanently deletes a contact list. Contacts in the list are not deleted but are removed from the list membership.
      tags:
      - Contact Lists
      parameters:
      - $ref: '#/components/parameters/listIdParam'
      responses:
        '204':
          description: List deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /contacts/lists/{listId}/contacts/add:
    post:
      operationId: addContactsToList
      summary: Add contacts to a list
      description: Adds one or more existing contacts to a contact list using their email addresses or internal IDs.
      tags:
      - Contact Lists
      parameters:
      - $ref: '#/components/parameters/listIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  description: List of email addresses to add to the list.
                  items:
                    type: string
                    format: email
                ids:
                  type: array
                  description: List of contact IDs to add to the list.
                  items:
                    type: integer
                    format: int64
      responses:
        '201':
          description: Contacts added to list successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: object
                    description: Summary of contacts added and failed.
                    properties:
                      success:
                        type: array
                        description: Successfully added contact identifiers.
                        items:
                          type: string
                      failure:
                        type: array
                        description: Failed contact identifiers.
                        items:
                          type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /contacts/lists/{listId}/contacts/remove:
    post:
      operationId: removeContactsFromList
      summary: Remove contacts from a list
      description: Removes one or more contacts from a contact list. The contacts themselves are not deleted from the account.
      tags:
      - Contact Lists
      parameters:
      - $ref: '#/components/parameters/listIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  description: List of email addresses to remove from the list.
                  items:
                    type: string
                    format: email
                ids:
                  type: array
                  description: List of contact IDs to remove from the list.
                  items:
                    type: integer
                    format: int64
      responses:
        '201':
          description: Contacts removed from list successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: object
                    description: Summary of contacts removed and failed.
                    properties:
                      success:
                        type: array
                        description: Successfully removed contact identifiers.
                        items:
                          type: string
                      failure:
                        type: array
                        description: Failed contact identifiers.
                        items:
                          type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: List not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    UpdateContactList:
      type: object
      properties:
        name:
          type: string
          description: Updated name for the list.
        folderId:
          type: integer
          format: int64
          description: Updated folder assignment.
    CreateContactList:
      type: object
      required:
      - name
      - folderId
      properties:
        name:
          type: string
          description: Name for the new contact list.
        folderId:
          type: integer
          format: int64
          description: ID of the folder to place the list in.
    ContactListCollection:
      type: object
      properties:
        count:
          type: integer
          format: int64
          description: Total number of contact lists.
        lists:
          type: array
          description: List of contact list summaries.
          items:
            $ref: '#/components/schemas/ContactListDetail'
    ContactListDetail:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the list.
        name:
          type: string
          description: Name of the list.
        totalSubscribers:
          type: integer
          format: int64
          description: Total number of subscribers in the list.
        totalBlacklisted:
          type: integer
          format: int64
          description: Total number of blacklisted contacts in the list.
        folderId:
          type: integer
          format: int64
          description: ID of the folder containing the list.
        createdAt:
          type: string
          format: date-time
          description: UTC date-time when the list was created.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code identifying the type of error.
        message:
          type: string
          description: Human-readable description of the error.
  parameters:
    offsetParam:
      name: offset
      in: query
      description: Number of results to skip for pagination.
      schema:
        type: integer
        format: int64
        default: 0
    listIdParam:
      name: listId
      in: path
      required: true
      description: Unique identifier of the contact list.
      schema:
        type: integer
        format: int64
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per request.
      schema:
        type: integer
        format: int64
        default: 50
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Brevo API key passed in the api-key request header for authentication.
externalDocs:
  description: Brevo Contacts Documentation
  url: https://developers.brevo.com/docs/how-it-works