brevo Contacts API

openapi: 3.1.0
info:
  title: Brevo Agent Status Contacts 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: Contacts
  description: Create, retrieve, update, and delete individual contacts.
paths:
  /contacts:
    get:
      operationId: listContacts
      summary: Get all contacts
      description: Retrieves a paginated list of contacts from the account. Supports filtering by modification date and sorting. The response includes contact attributes and list memberships.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: modifiedSince
        in: query
        description: Filter contacts modified since this date-time in ISO 8601 format.
        schema:
          type: string
          format: date-time
      - name: sort
        in: query
        description: Sort direction for the results.
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Contacts retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createContact
      summary: Create a contact
      description: Creates a new contact with the specified email address and optional attributes. The contact can be immediately added to one or more lists. Duplicate email addresses will result in an update of the existing contact if updateEnabled is set.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContact'
      responses:
        '201':
          description: Contact created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    description: Unique identifier of the newly created contact.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /contacts/{identifier}:
    get:
      operationId: getContactInfo
      summary: Get a contact's details
      description: Retrieves detailed information about a specific contact including all attributes, list memberships, and email campaign statistics. The contact can be identified by email address, phone number, or internal ID.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactIdentifierParam'
      - name: startDate
        in: query
        description: Start date for retrieving contact statistics.
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: End date for retrieving contact statistics.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Contact details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateContact
      summary: Update a contact
      description: Updates an existing contact's attributes and list memberships. The contact is identified by email address, phone number, or internal ID.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactIdentifierParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContact'
      responses:
        '204':
          description: Contact 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: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteContact
      summary: Delete a contact
      description: Permanently deletes a contact from the account. The contact is identified by email address, phone number, or internal ID.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactIdentifierParam'
      responses:
        '204':
          description: Contact deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreateContact:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address of the new contact.
        attributes:
          type: object
          description: Custom attribute values as key-value pairs.
          additionalProperties: true
        listIds:
          type: array
          description: IDs of lists to add the contact to.
          items:
            type: integer
            format: int64
        updateEnabled:
          type: boolean
          description: Whether to update the contact if a duplicate email exists.
          default: false
        smtpBlacklistSender:
          type: array
          description: Sender email addresses to blacklist for this contact.
          items:
            type: string
            format: email
    ContactList:
      type: object
      properties:
        count:
          type: integer
          format: int64
          description: Total number of contacts in the account.
        contacts:
          type: array
          description: List of contact records.
          items:
            $ref: '#/components/schemas/Contact'
    Contact:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the contact.
        email:
          type: string
          format: email
          description: Email address of the contact.
        emailBlacklisted:
          type: boolean
          description: Whether the contact's email is blacklisted.
        smsBlacklisted:
          type: boolean
          description: Whether the contact's phone number is blacklisted for SMS.
        modifiedAt:
          type: string
          format: date-time
          description: UTC date-time when the contact was last modified.
        createdAt:
          type: string
          format: date-time
          description: UTC date-time when the contact was created.
        listIds:
          type: array
          description: IDs of lists the contact belongs to.
          items:
            type: integer
            format: int64
        attributes:
          type: object
          description: Custom attribute values for the contact as key-value pairs.
          additionalProperties: true
    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.
    UpdateContact:
      type: object
      properties:
        attributes:
          type: object
          description: Custom attribute values to update as key-value pairs.
          additionalProperties: true
        listIds:
          type: array
          description: IDs of lists to set for the contact.
          items:
            type: integer
            format: int64
        unlinkListIds:
          type: array
          description: IDs of lists to remove the contact from.
          items:
            type: integer
            format: int64
        emailBlacklisted:
          type: boolean
          description: Whether to blacklist the contact's email.
        smsBlacklisted:
          type: boolean
          description: Whether to blacklist the contact's phone for SMS.
  parameters:
    offsetParam:
      name: offset
      in: query
      description: Number of results to skip for pagination.
      schema:
        type: integer
        format: int64
        default: 0
    contactIdentifierParam:
      name: identifier
      in: path
      required: true
      description: Contact identifier which can be an email address, phone number, or internal contact ID.
      schema:
        type: string
    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