brevo Contacts API

openapi: 3.2.0
info:
  title: Brevo Contacts API
  version: '1.0'
  description: 'Operations tagged contacts across 2 of this provider''s published API definitions: brevo-contact-management-openapi.yml, brevo-contacts-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.brevo.com/v3
  description: https://api.brevo.com/v3
tags:
- name: contacts
paths:
  /contacts/attributes/{attributeCategory}/{attributeName}:
    post:
      operationId: createAttribute
      summary: Create contact attribute
      description: 'Create a new contact attribute under the specified category and name. The required body properties depend on the category: use "type" for normal, transactional, or category attributes; use "value" for calculated or global attributes; use "enumeration" for category attributes; and use "multiCategoryOptions" for normal multiple-choice attributes. None of the category or multicategory option values can exceed 200 characters.'
      tags:
      - contacts
      parameters:
      - name: attributeCategory
        in: path
        description: Category of the attribute
        required: true
        schema:
          $ref: '#/components/schemas/ContactsAttributesAttributeCategoryAttributeNamePostParametersAttributeCategory'
      - name: attributeName
        in: path
        description: Name of the attribute
        required: true
        schema:
          type: string
      - 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: Attribute created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contacts_createAttribute_Response_201'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAttributeRequestBadRequestError'
      requestBody:
        description: Values to create an attribute
        content:
          application/json:
            schema:
              type: object
              properties:
                enumeration:
                  type: array
                  items:
                    $ref: '#/components/schemas/ContactsAttributesAttributeCategoryAttributeNamePostRequestBodyContentApplicationJsonSchemaEnumerationItems'
                  description: 'List of values and labels that the attribute can take. **Use only if the attribute''s category is "category"**. None of the category options can exceed max 200 characters. For example: **[{"value":1, "label":"male"}, {"value":2, "label":"female"}]**

                    '
                isRecurring:
                  type: boolean
                  description: 'Type of the attribute. **Use only if the attribute''s category is ''calculated'' or ''global''**

                    '
                multiCategoryOptions:
                  type: array
                  items:
                    type: string
                  description: 'List of options you want to add for multiple-choice attribute. **Use only if the attribute''s category is "normal" and attribute''s type is "multiple-choice". None of the multicategory options can exceed max 200 characters.** For example: **["USA","INDIA"]**

                    '
                type:
                  $ref: '#/components/schemas/ContactsAttributesAttributeCategoryAttributeNamePostRequestBodyContentApplicationJsonSchemaType'
                  description: 'Type of the attribute. **Use only if the attribute''s category is ''normal'', ''category'' or ''transactional''** Type **user and multiple-choice** is only available if the category is **normal** attribute Type **id** is only available if the category is **transactional** attribute Type **category** is only available if the category is **category** attribute

                    '
                value:
                  type: string
                  description: 'Value of the attribute. **Use only if the attribute''s category is ''calculated'' or ''global''**

                    '
    put:
      operationId: updateAttribute
      summary: Update contact attribute
      description: Update an existing contact attribute identified by its category and name. For category-type attributes, you can update the enumeration values; for calculated or global attributes, update the computed value formula; and for normal multiple-choice attributes, update the multicategory options. None of the category or multicategory option values can exceed 200 characters.
      tags:
      - contacts
      parameters:
      - name: attributeCategory
        in: path
        description: Category of the attribute
        required: true
        schema:
          $ref: '#/components/schemas/ContactsAttributesAttributeCategoryAttributeNamePutParametersAttributeCategory'
      - name: attributeName
        in: path
        description: Name of the existing attribute
        required: true
        schema:
          type: string
      - 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: Attribute updated
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAttributeRequestBadRequestError'
        '404':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAttributeRequestNotFoundError'
      requestBody:
        description: Values to update an attribute
        content:
          application/json:
            schema:
              type: object
              properties:
                enumeration:
                  type: array
                  items:
                    $ref: '#/components/schemas/ContactsAttributesAttributeCategoryAttributeNamePutRequestBodyContentApplicationJsonSchemaEnumerationItems'
                  description: 'List of the values and labels that the attribute can take. **Use only if the attribute''s category is "category"** None of the category options can exceed max 200 characters. For example, **[{"value":1, "label":"male"}, {"value":2, "label":"female"}]**

                    '
                multiCategoryOptions:
                  type: array
                  items:
                    type: string
                  description: 'Use this option to add multiple-choice attributes options only if the attribute''s category is "normal". **This option is specifically designed for updating multiple-choice attributes. None of the multicategory options can exceed max 200 characters.**. For example: **["USA","INDIA"]**

                    '
                value:
                  type: string
                  description: 'Value of the attribute to update. **Use only if the attribute''s category is ''calculated'' or ''global''**

                    '
    delete:
      operationId: deleteAttribute
      summary: Delete an attribute
      description: Permanently delete an existing contact attribute by its category and name. The attribute must exist in the specified category (normal, transactional, category, calculated, or global), otherwise a 404 error is returned.
      tags:
      - contacts
      parameters:
      - name: attributeCategory
        in: path
        description: Category of the attribute
        required: true
        schema:
          $ref: '#/components/schemas/ContactsAttributesAttributeCategoryAttributeNameDeleteParametersAttributeCategory'
      - name: attributeName
        in: path
        description: Name of the existing attribute
        required: true
        schema:
          type: string
      - 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: Attribute deleted
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAttributeRequestBadRequestError'
        '404':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAttributeRequestNotFoundError'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/attributes:
    get:
      operationId: getAttributes
      summary: List all attributes
      description: Retrieve all contact attributes defined in your Brevo account, grouped by category (normal, transactional, category, calculated, global). Each attribute includes its name, type, and category, along with enumeration values for category-type attributes and options for multiple-choice-type attributes.
      tags:
      - contacts
      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:
        '200':
          description: Attributes listed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contacts_getAttributes_Response_200'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAttributesRequestBadRequestError'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/attributes/{attributeType}/{multipleChoiceAttribute}/{multipleChoiceAttributeOption}:
    delete:
      operationId: deleteMultiAttributeOptions
      summary: Delete a multiple-choice attribute option
      description: Delete a specific option from an existing multiple-choice contact attribute. The attribute type must be "multiple-choice", and both the attribute name and the option to delete must already exist in your account.
      tags:
      - contacts
      parameters:
      - name: attributeType
        in: path
        description: Type of the attribute
        required: true
        schema:
          $ref: '#/components/schemas/ContactsAttributesAttributeTypeMultipleChoiceAttributeMultipleChoiceAttributeOptionDeleteParametersAttributeType'
      - name: multipleChoiceAttribute
        in: path
        description: Name of the existing multiple-choice attribute
        required: true
        schema:
          type: string
      - name: multipleChoiceAttributeOption
        in: path
        description: Name of the existing multiple-choice attribute option that you want to delete
        required: true
        schema:
          type: string
      - 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: Multiple-Choice Attribute Option Deleted Successfully.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMultiAttributeOptionsRequestBadRequestError'
        '404':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMultiAttributeOptionsRequestNotFoundError'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/lists:
    post:
      operationId: createList
      summary: Create a list
      description: Create a new contact list inside a specified folder. Both the list name and the parent folder ID are required. The newly created list will be empty and ready to receive contacts via the add contacts endpoint.
      tags:
      - contacts
      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: successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contacts_createList_Response_201'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateListRequestBadRequestError'
      requestBody:
        description: Values to create a list
        content:
          application/json:
            schema:
              type: object
              properties:
                folderId:
                  type: integer
                  format: int64
                  description: Id of the parent folder in which this list is to be created
                name:
                  type: string
                  description: Name of the list
              required:
              - folderId
              - name
    get:
      operationId: getLists
      summary: Get all the lists
      description: '<Note>Ongoing changes for this endpoint.

        We''re dropping support for the response attributes totalSubscribers and totalBlacklisted.

        These are non breaking changes. The default value for the attributes will be 0.</Note>'
      tags:
      - contacts
      parameters:
      - name: limit
        in: query
        description: Number of documents per page
        required: false
        schema:
          type: integer
          format: int64
          default: 10
      - name: offset
        in: query
        description: Index of the first document of the page
        required: false
        schema:
          type: integer
          format: int64
          default: 0
      - name: sort
        in: query
        description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
        required: false
        schema:
          $ref: '#/components/schemas/ContactsListsGetParametersSort'
          default: desc
      - 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: Lists informations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contacts_getLists_Response_200'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListsRequestBadRequestError'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/lists/{listId}:
    get:
      operationId: getList
      summary: Get a list's details
      description: Retrieve the details of a specific contact list by its ID, including its name, folder ID, creation date, subscriber counts, and campaign statistics. You can optionally filter campaign statistics by providing startDate and endDate parameters (both must be used together in YYYY-MM-DD format).
      tags:
      - contacts
      parameters:
      - name: listId
        in: path
        description: Id of the list
        required: true
        schema:
          type: integer
          format: int64
      - name: startDate
        in: query
        description: '**Mandatory if endDate is used**. Starting (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to aggregate the sent email campaigns for a specific list id. **Prefer to pass your timezone in date-time format for accurate result**

          '
        required: false
        schema:
          type: string
      - name: endDate
        in: query
        description: '**Mandatory if startDate is used**. Ending (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to aggregate the sent email campaigns for a specific list id. **Prefer to pass your timezone in date-time format for accurate result**

          '
        required: false
        schema:
          type: string
      - 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: List informations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contacts_getList_Response_200'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListRequestBadRequestError'
        '404':
          description: List ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
    put:
      operationId: updateList
      summary: Update a list
      description: Update an existing contact list identified by its ID. You can update the list name, move it to a different folder by providing a new folderId, or both. Only one of the two parameters (name, folderId) needs to be provided per request.
      tags:
      - contacts
      parameters:
      - name: listId
        in: path
        description: Id of the list
        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: List updated
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateListRequestBadRequestError'
        '404':
          description: List ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
      requestBody:
        description: Values to update a list
        content:
          application/json:
            schema:
              type: object
              properties:
                folderId:
                  type: integer
                  format: int64
                  description: Id of the folder in which the list is to be moved. Either of the two parameters (name, folderId) can be updated at a time.
                name:
                  type: string
                  description: Name of the list. Either of the two parameters (name, folderId) can be updated at a time.
    delete:
      operationId: deleteList
      summary: Delete a list
      description: Permanently delete a contact list identified by its ID. The contacts in the list are not deleted; they are only removed from this list. Returns a 404 error if the list ID does not exist.
      tags:
      - contacts
      parameters:
      - name: listId
        in: path
        description: Id of the list
        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: List deleted
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteListRequestBadRequestError'
        '404':
          description: List ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/lists/{listId}/contacts:
    get:
      operationId: getContactsFromList
      summary: Get contacts in a list
      description: Retrieve all contacts belonging to a specific list, identified by its list ID. Results are paginated with a default of 50 contacts per page (maximum 500) and sorted in descending order of creation. You can optionally filter contacts by their modification date using the modifiedSince parameter.
      tags:
      - contacts
      parameters:
      - name: listId
        in: path
        description: Id of the list
        required: true
        schema:
          type: integer
          format: int64
      - name: modifiedSince
        in: query
        description: 'Filter (urlencoded) the contacts modified after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.**

          '
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of documents per page
        required: false
        schema:
          type: integer
          format: int64
          default: 50
      - name: offset
        in: query
        description: Index of the first document of the page
        required: false
        schema:
          type: integer
          format: int64
          default: 0
      - name: sort
        in: query
        description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
        required: false
        schema:
          $ref: '#/components/schemas/ContactsListsListIdContactsGetParametersSort'
          default: desc
      - 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: Contact informations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getContacts'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetContactsFromListRequestBadRequestError'
        '404':
          description: List ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/lists/{listId}/contacts/remove:
    post:
      operationId: removeContactFromList
      summary: Delete a contact from a list
      tags:
      - contacts
      parameters:
      - name: listId
        in: path
        description: Id of the list
        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:
        '201':
          description: All contacts have been removed successfully from the list with details of failed ones
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postContactInfo'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveContactFromListRequestBadRequestError'
        '404':
          description: List ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
      requestBody:
        description: Emails adresses OR IDs OR EXT_ID attributes of the contacts OR 'all' true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contacts_removeContactFromList_Request'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/lists/{listId}/contacts/add:
    post:
      operationId: addContactToList
      summary: Add existing contacts to a list
      tags:
      - contacts
      parameters:
      - name: listId
        in: path
        description: Id of the list
        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:
        '201':
          description: All contacts have been added successfully to the list with details of failed ones
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postContactInfo'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddContactToListRequestBadRequestError'
        '404':
          description: List ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
      requestBody:
        description: Emails addresses OR IDs OR EXT_ID attributes of the contacts
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contacts_addContactToList_Request'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/folders:
    post:
      operationId: createFolder
      summary: Create a folder
      description: Create a new folder to organize your contact lists. Folders serve as containers for grouping related lists together. The folder name is required and must be provided in the request body.
      tags:
      - contacts
      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: successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contacts_createFolder_Response_201'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFolderRequestBadRequestError'
      requestBody:
        description: Name of the folder
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createUpdateFolder'
    get:
      operationId: getFolders
      summary: Get all folders
      description: '<Note>Ongoing changes for this endpoint

        We''re dropping support for the response attributes totalSubscribers and totalBlacklisted.

        These are non breaking changes.

        The default value for the attributes will be 0.

        The uniqueSubscribers field is deprecated</Note>'
      tags:
      - contacts
      parameters:
      - name: limit
        in: query
        description: Number of documents per page
        required: false
        schema:
          type: integer
          format: int64
          default: 10
      - name: offset
        in: query
        description: Index of the first document of the page
        required: false
        schema:
          type: integer
          format: int64
          default: 0
      - name: sort
        in: query
        description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
        required: false
        schema:
          $ref: '#/components/schemas/ContactsFoldersGetParametersSort'
          default: desc
      - 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: Folders informations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contacts_getFolders_Response_200'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFoldersRequestBadRequestError'
    servers:
    - url: https://api.brevo.com/v3
      description: https://api.brevo.com/v3
  /contacts/folders/{folderId}:
    get:
      operationId: getFolder
      summary: Returns a folder's details
      description: '<Note>Ongoing changes for this endpoint.

        We''re dropping support for the response attributes totalSubscribers and totalBlacklisted.

        These are non breaking changes. The default value for the attributes will be 0.</Note>'
      tags:
      - contacts
      parameters:
      - name: folderId
        in: path
        description: id of the folder
        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: Folder details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getFolder'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFolderRequestBadRequestError'
        '404':
          description: Folder ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
    put:
      operationId: updateFolder
      summary: Update a folder
      description: Update the name of an existing folder identified by its ID. The new folder name must be provided in the request body. Returns a 404 error if the folder ID does not exist.
      tags:
      - contacts
      parameters:
      - name: folderId
        in: path
        description: Id of the folder
        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: Folder updated
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateFolderRequestBadRequestError'
        '404':
          description: Folder ID not found
   

# --- truncated at 32 KB (182 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brevo/refs/heads/main/openapi/brevo-contacts-api-openapi.yml