Manage the Brevo Sales CRM object graph — deals, companies, tasks, notes, files and pipelines — including linking and unlinking deals to contacts and companies, bulk import, and server-side filtering of deals by owner, stage and pipeline.
openapi: 3.1.0
info:
title: Sales CRM
version: 1.0.0
paths:
/companies:
get:
operationId: getAllCompanies
summary: Get all Companies
description: >-
Retrieve a paginated list of companies with optional filtering, sorting, and search capabilities. Results are
sorted by creation date in descending order by default, and can be filtered by attributes, linked contacts,
linked deals, or modification/creation timestamps.
tags:
- companies
parameters:
- name: filters[attributes.name]
in: query
description: >-
Filter by attributes. If you have a filter for the owner on your side please send it as
filters[attributes.owner] and utilize the account email for the filtering.
required: false
schema:
type: string
- name: linkedContactsIds
in: query
description: Filter by linked contacts ids
required: false
schema:
type: integer
format: int64
- name: linkedDealsIds
in: query
description: Filter by linked Deals ids
required: false
schema:
type: string
format: objectID
- name: modifiedSince
in: query
description: >-
Filter (urlencoded) the companies 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: createdSince
in: query
description: >-
Filter (urlencoded) the companies created 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: page
in: query
description: Index of the first document of the page
required: false
schema:
type: integer
format: int64
- name: limit
in: query
description: Number of documents per page
required: false
schema:
type: integer
format: int64
- name: sort
in: query
description: >-
Sort the results in the ascending/descending order. Default order is **descending** by creation if `sort` is
not passed
required: false
schema:
$ref: '#/components/schemas/CompaniesGetParametersSort'
- name: sortBy
in: query
description: The field used to sort field names.
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: Returns companies list with filters
content:
application/json:
schema:
$ref: '#/components/schemas/Companies_getAllCompanies_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetAllCompaniesRequestBadRequestError'
post:
operationId: createACompany
summary: Create a company
description: >-
Create a new CRM company with the specified name, attributes, and optional associations to contacts and deals.
The company name is required, and you can optionally provide a country code when a phone number attribute is
included.
tags:
- companies
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: Created new Company
content:
application/json:
schema:
$ref: '#/components/schemas/Companies_createACompany_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateACompanyRequestBadRequestError'
requestBody:
description: Company create data.
content:
application/json:
schema:
type: object
properties:
attributes:
$ref: '#/components/schemas/CompaniesPostRequestBodyContentApplicationJsonSchemaAttributes'
description: Attributes for company creation
countryCode:
type: integer
format: int64
description: Country code if phone_number is passed in attributes.
linkedContactsIds:
type: array
items:
type: integer
format: int64
description: Contact ids to be linked with company
linkedDealsIds:
type: array
items:
type: string
format: objectID
description: Deal ids to be linked with company
name:
type: string
description: Name of company
required:
- name
/companies/{id}:
get:
operationId: getACompany
summary: Get a company
description: >-
Retrieve the full details of a single company by its identifier, including its attributes, linked contacts, and
linked deals. Returns a 404 error if the company does not exist, or a 403 error if the user lacks permission to
view the company.
tags:
- companies
parameters:
- name: id
in: path
description: Get Company Details
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:
'200':
description: Returns the Company
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetACompanyRequestBadRequestError'
'404':
description: Returned when item not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
delete:
operationId: deleteACompany
summary: Delete a company
description: >-
Permanently delete a company by its identifier. The requesting user must be the company owner or have manage
permission on companies; otherwise, a 403 Forbidden error is returned.
tags:
- companies
parameters:
- name: id
in: path
description: Company ID 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: When company deleted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteACompanyRequestBadRequestError'
'404':
description: Returned when item not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
patch:
operationId: updateACompany
summary: Update a company
description: >-
Update an existing company''s attributes, name, linked contacts, or linked deals. Note that passing
`linkedContactsIds` or `linkedDealsIds` replaces the entire list of associations, so omitted IDs will be
removed. The company name cannot be set to an empty string.
tags:
- companies
parameters:
- name: id
in: path
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:
'200':
description: Company updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateACompanyRequestBadRequestError'
'404':
description: Returned when company id is not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
requestBody:
description: Updated company details.
content:
application/json:
schema:
type: object
properties:
attributes:
$ref: '#/components/schemas/CompaniesIdPatchRequestBodyContentApplicationJsonSchemaAttributes'
description: Attributes for company update
countryCode:
type: integer
format: int64
description: Country code if phone_number is passed in attributes.
linkedContactsIds:
type: array
items:
type: integer
format: int64
description: >-
Warning - Using PATCH on linkedContactIds replaces the list of linked contacts. Omitted IDs will be
removed.
linkedDealsIds:
type: array
items:
type: string
format: objectID
description: >-
Warning - Using PATCH on linkedDealsIds replaces the list of linked deals. Omitted IDs will be
removed.
name:
type: string
description: Name of company
/crm/attributes:
post:
operationId: createACompanyDealAttribute
summary: Create a company/deal attribute
description: >-
Create a new custom attribute for companies or deals. The attribute label must be unique within the object type,
cannot exceed 50 characters, and cannot use reserved names. For `single-select` or `multi-choice` attribute
types, you must also provide the `optionsLabels` array.
tags:
- companies
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: Created new attribute
content:
application/json:
schema:
$ref: '#/components/schemas/Companies_createACompanyDealAttribute_Response_200'
'400':
description: Returned when invalid data is posted
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
requestBody:
description: Attribute creation data for a company/deal.
content:
application/json:
schema:
type: object
properties:
attributeType:
$ref: '#/components/schemas/CrmAttributesPostRequestBodyContentApplicationJsonSchemaAttributeType'
description: The type of attribute (must be one of the defined enums)
description:
type: string
description: A description of the attribute
label:
type: string
description: The label for the attribute (max 50 characters, cannot be empty)
objectType:
$ref: '#/components/schemas/CrmAttributesPostRequestBodyContentApplicationJsonSchemaObjectType'
description: The type of object the attribute belongs to. Must be either `companies` or `deals`.
optionsLabels:
type: array
items:
type: string
description: Options for multi-choice or single-select attributes
required:
- attributeType
- label
- objectType
/crm/attributes/companies:
get:
operationId: getCompanyAttributes
summary: Get company attributes
description: >-
Retrieve the list of all attributes defined for companies, including both system-default and custom attributes.
Each attribute includes its label, internal name, type, required status, and available options for select-type
attributes.
tags:
- companies
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: Returns list of company attributes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CrmAttributesCompaniesGetResponsesContentApplicationJsonSchemaItems'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetCompanyAttributesRequestBadRequestError'
/companies/link-unlink/{id}:
patch:
operationId: linkAndUnlinkCompanyWithContactAndDeal
summary: Link and Unlink company with contact and deal
description: >-
Link or unlink contacts and deals with a specific company in a single request. You can simultaneously link new
contacts/deals and unlink existing ones by providing the respective ID arrays in the request body.
tags:
- companies
parameters:
- name: id
in: path
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: Successfully linked/unlinked contacts and deals with the company.
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/LinkAndUnlinkCompanyWithContactAndDealRequestBadRequestError'
requestBody:
description: Linked / Unlinked contacts and deals ids.
content:
application/json:
schema:
type: object
properties:
linkContactIds:
type: array
items:
type: integer
format: int64
description: Contact ids for contacts to be linked with company
linkDealsIds:
type: array
items:
type: string
description: Deal ids for deals to be linked with company
unlinkContactIds:
type: array
items:
type: integer
format: int64
description: Contact ids for contacts to be unlinked from company
unlinkDealsIds:
type: array
items:
type: string
description: Deal ids for deals to be unlinked from company
/companies/import:
post:
operationId: importCompaniesCreationAndUpdation
summary: Import companies(creation and updation)
description: Import companies from a CSV file with mapping options.
tags:
- companies
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: Successfully imported companies
content:
application/json:
schema:
$ref: '#/components/schemas/Companies_importCompaniesCreationAndUpdation_Response_200'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ImportCompaniesCreationAndUpdationRequestBadRequestError'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: >
The CSV file to upload.The file should have the first row as the mapping attribute. Some default
attribute names are (a) company_id [brevo mongoID to update companies] (b) associated_contact (c)
associated_deal (f) any other attribute with internal name
mapping:
$ref: '#/components/schemas/CompaniesImportPostRequestBodyContentMultipartFormDataSchemaMapping'
description: |
The mapping options in JSON format. Here is an example of the JSON structure: ```json {
"link_entities": true, // Determines whether to link related entities during the import process
"unlink_entities": false, // Determines whether to unlink related entities during the import process
"update_existing_records": true, // Determines whether to update based on company ID or treat every row as create
"unset_empty_attributes": false // Determines whether to unset a specific attribute during update if the values input is blank
} ```
/crm/pipeline/details:
get:
operationId: getPipelineStages
summary: Get pipeline stages
description: This endpoint is deprecated. Prefer /crm/pipeline/details/{pipelineID} instead.
tags:
- deals
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: Returns list of pipeline stages
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetPipelineStagesRequestBadRequestError'
/crm/pipeline/details/{pipelineID}:
get:
operationId: getAPipeline
summary: Get a pipeline
description: >-
Retrieve the details of a specific deal pipeline by its identifier, including its stages, stage ordering, and
configuration. Use this endpoint to obtain the pipeline and stage IDs needed when creating or updating deals.
tags:
- deals
parameters:
- name: pipelineID
in: path
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:
'200':
description: Returns pipeline and its details
content:
application/json:
schema:
$ref: '#/components/schemas/Pipelines'
'400':
description: Returned when pipeline id is invalid or does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
/crm/pipeline/details/all:
get:
operationId: getAllPipelines
summary: Get all pipelines
description: >-
Retrieve the list of all deal pipelines configured for your account, including each pipeline''s stages and
settings. If no pipelines have been configured yet, a default pipeline is automatically created and returned.
tags:
- deals
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: Returns list of pipelines and their details
content:
application/json:
schema:
$ref: '#/components/schemas/Pipelines'
'400':
description: Returned when pipeline id is invalid or does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
/crm/attributes/deals:
get:
operationId: getDealAttributes
summary: Get deal attributes
description: >-
Retrieve the list of all attributes defined for deals, including both system-default and custom attributes. Each
attribute includes its label, internal name, type, required status, and available options for select-type
attributes.
tags:
- deals
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: Returns list of deal attributes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CrmAttributesDealsGetResponsesContentApplicationJsonSchemaItems'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetDealAttributesRequestBadRequestError'
/crm/deals:
get:
operationId: getAllDeals
summary: Get all deals
description: >-
Retrieve a paginated list of deals with optional filtering, sorting, and search capabilities. Results can be
filtered by attributes such as deal name or owner, linked companies, linked contacts, or modification/creation
timestamps. Default sort order is descending by creation date.
tags:
- deals
parameters:
- name: filters[attributes.deal_name]
in: query
description: >-
Filter by attributes. If you have a filter for the owner on your end, please send it as
filters[attributes.deal_owner] and utilize the account email for the filtering.
required: false
schema:
type: string
- name: filters[attributes.deal_owner]
in: query
description: Filter by the deal owner. Pass the account email address of the deal owner.
required: false
schema:
type: string
- name: filters[attributes.deal_stage]
in: query
description: Filter by the deal stage. Pass the stage id, retrievable from GET /crm/pipeline/details/{pipelineID}.
required: false
schema:
type: string
- name: filters[attributes.pipeline]
in: query
description: Filter by the pipeline. Pass the pipeline id, retrievable from GET /crm/pipeline/details/{pipelineID}.
required: false
schema:
type: string
- name: filters[linkedCompaniesIds]
in: query
description: Filter by linked companies ids
required: false
schema:
type: string
- name: filters[linkedContactsIds]
in: query
description: Filter by linked contacts ids
required: false
schema:
type: string
- name: modifiedSince
in: query
description: >-
Filter (urlencoded) the deals 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: createdSince
in: query
description: >-
Filter (urlencoded) the deals created 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: offset
in: query
description: Index of the first document of the page
required: false
schema:
type: integer
format: int64
- name: limit
in: query
description: Number of documents per page
required: false
schema:
type: integer
format: int64
default: 50
- name: sort
in: query
description: >-
Sort the results in the ascending/descending order. Default order is **descending** by creation if `sort` is
not passed
required: false
schema:
$ref: '#/components/schemas/CrmDealsGetParametersSort'
- name: sortBy
in: query
description: The field used to sort field names.
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: Returns deals list with filters
content:
application/json:
schema:
$ref: '#/components/schemas/Deals_getAllDeals_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetAllDealsRequestBadRequestError'
post:
operationId: createADeal
summary: Create a deal
description: >-
Create a new deal in the CRM with the specified name, attributes, and optional associations to contacts and
companies. You can assign the deal to a specific pipeline and stage by providing `pipeline` and `deal_stage`
attribute IDs, which can be retrieved from the pipeline details endpoint.
tags:
- deals
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: Created new Deal
content:
application/json:
schema:
$ref: '#/components/schemas/Deals_createADeal_Response_201'
'400':
description: Returned when invalid data posted
content:
application/json:
schema:
description: Any type
requestBody:
description: Deal create data.
content:
application/json:
schema:
type: object
properties:
attributes:
$ref: '#/components/schemas/CrmDealsPostRequestBodyContentApplicationJsonSchemaAttributes'
description: >
Attributes for deal creation To assign owner of a Deal you can send attributes.deal_owner and
utilize the account email or ID. If you want to create a deal on a specific pipeline and stage you
can use the following attributes `pipeline` and `deal_stage`. Pipeline and deal_stage are ids you
can fetch using this endpoint `/crm/pipeline/details/{pipelineID}`
linkedCompaniesIds:
type: array
items:
type: string
format: objectID
description: Company ids to be linked with deal
linkedContactsIds:
type: array
items:
type: integer
format: int64
description: Contact ids to be linked with deal
name:
type: string
description: Name of deal
required:
- name
/crm/deals/{id}:
get:
operationId: getADeal
summary: Get a deal
description: >-
Retrieve the full details of a single deal by its identifier, including its attributes, pipeline stage, linked
contacts, and linked companies. Returns a 404 error if the deal does not exist.
tags:
- deals
parameters:
- name: id
in: path
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:
'200':
description: Returns the deal by id
content:
application/json:
schema:
$ref: '#/components/schemas/Deal'
'400':
description: Returned when deal id is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
'404':
description: Returned when item not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
delete:
operationId: deleteADeal
summary: Delete a deal
description: >-
Permanently delete a deal by its identifier. The requesting user must be the deal owner or have manage
permission on deals; otherwise, a 403 Forbidden error is returned.
tags:
- deals
parameters:
- name: id
in: path
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: Returned when item deleted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteADealRequestBadRequestErr
# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brevo/refs/heads/main/openapi/brevo-sales-crm-openapi.yml