openapi: 3.2.0 info: title: Sales CRM Deals API version: 1.0.0 servers: - url: https://api.brevo.com/v3 description: https://api.brevo.com/v3 tags: - name: deals paths: /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/DeleteADealRequestBadRequestError' '404': description: Returned when deal id is not found content: application/json: schema: $ref: '#/components/schemas/errorModel' patch: operationId: updateADeal summary: Update a deal description: Update an existing deal''s attributes, name, linked contacts, or linked companies. Note that passing `linkedContactsIds` or `linkedCompaniesIds` replaces the entire list of associations, so omitted IDs will be removed. To move a deal to a different pipeline or stage, provide both the `pipeline` and `deal_stage` attribute IDs. 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: Deal updated successfully content: application/json: schema: type: object properties: {} '400': description: bad request content: application/json: schema: $ref: '#/components/schemas/UpdateADealRequestBadRequestError' '404': description: Returned when deal id is not found content: application/json: schema: $ref: '#/components/schemas/errorModel' requestBody: description: Updated deal details. content: application/json: schema: type: object properties: attributes: $ref: '#/components/schemas/CrmDealsIdPatchRequestBodyContentApplicationJsonSchemaAttributes' description: 'Attributes for deal update To assign owner of a Deal you can send attributes.deal_owner and utilize the account email or ID. If you wish to update the pipeline of a deal you need to provide the `pipeline` and the `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: Warning - Using PATCH on linkedCompaniesIds replaces the list of linked companies. Omitted IDs will be removed. 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. name: type: string description: Name of deal /crm/deals/link-unlink/{id}: patch: operationId: linkAndUnlinkADealWithContactsAndCompanies summary: Link and Unlink a deal with contacts and companies description: Link or unlink contacts and companies with a specific deal in a single request. You can simultaneously link new contacts/companies and unlink existing ones by providing the respective ID arrays in the request body. 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: Successfully linked/unlinked contacts/companies with the deal. content: application/json: schema: type: object properties: {} '400': description: Returned when query params are invalid or invalid data provided in request. content: application/json: schema: $ref: '#/components/schemas/errorModel' requestBody: description: Linked / Unlinked contacts and companies ids. content: application/json: schema: type: object properties: linkCompanyIds: type: array items: type: string description: Company ids to be linked with deal linkContactIds: type: array items: type: integer format: int64 description: Contact ids for contacts to be linked with deal unlinkCompanyIds: type: array items: type: string description: Company ids to be unlinked from deal unlinkContactIds: type: array items: type: integer format: int64 description: Contact ids for contacts to be unlinked from deal /crm/deals/import: post: operationId: importDealsCreationAndUpdation summary: Import deals(creation and updation) description: Import deals from a CSV file with mapping options. 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: Successfully imported deals content: application/json: schema: $ref: '#/components/schemas/Deals_importDealsCreationAndUpdation_Response_200' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ImportDealsCreationAndUpdationRequestBadRequestError' 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) deal_id [brevo mongoID to update deals] (b) associated_contact (c) associated_company (f) any other attribute with internal name ' mapping: $ref: '#/components/schemas/CrmDealsImportPostRequestBodyContentMultipartFormDataSchemaMapping' description: "The mapping options in JSON format. Here is an example of the JSON structure: ```json {\n \"link_entities\": true, // Determines whether to link related entities during the import process\n \"unlink_entities\": false, // Determines whether to unlink related entities during the import process\n \"update_existing_records\": true, // Determines whether to update based on deal ID or treat every row as create\n \"unset_empty_attributes\": false // Determines whether to unset a specific attribute during update if the values input is blank\n} ```\n" components: schemas: CrmDealsIdDeleteResponsesContentApplicationJsonSchemaCode: type: string enum: - invalid_parameter - missing_parameter - out_of_range - campaign_processing - campaign_sent - document_not_found - not_enough_credits - permission_denied - duplicate_parameter - duplicate_request - method_not_allowed - unauthorized - account_under_validation - not_acceptable - bad_request - unprocessable_entity - Domain does not exist - Contact email not found - Attribute not found - Category id not found - Invalid parameters passed - Record(s) for identifier not found - Returned when query params are invalid - Returned when invalid data posted - Feed not found - Campaign ID not found - api-key not found - DMARC policy requires domain authentication - DNS records not properly configured - Invalid OTP code provided - OTP code has expired - Domain already exists in your account - The sum of all IP weights must equal 100 - Authentication failed - Insufficient credits - Request already processed description: Error code displayed in case of a failure title: CrmDealsIdDeleteResponsesContentApplicationJsonSchemaCode Pipeline: type: object properties: pipeline: type: string description: Pipeline id pipeline_name: type: string description: Pipeline Name stages: type: array items: $ref: '#/components/schemas/PipelineStagesItems' description: List of pipeline stages description: Pipeline details with stages title: Pipeline DeleteADealRequestBadRequestError: type: object properties: code: $ref: '#/components/schemas/CrmDealsIdDeleteResponsesContentApplicationJsonSchemaCode' description: Error code displayed in case of a failure message: type: string description: Readable message associated to the failure required: - code - message title: DeleteADealRequestBadRequestError CrmAttributesDealsGetResponsesContentApplicationJsonSchemaItemsAttributeOptionsItems: type: object properties: key: type: string value: type: string title: CrmAttributesDealsGetResponsesContentApplicationJsonSchemaItemsAttributeOptionsItems CrmDealsGetResponsesContentApplicationJsonSchemaCode: type: string enum: - invalid_parameter - missing_parameter - out_of_range - campaign_processing - campaign_sent - document_not_found - not_enough_credits - permission_denied - duplicate_parameter - duplicate_request - method_not_allowed - unauthorized - account_under_validation - not_acceptable - bad_request - unprocessable_entity - Domain does not exist - Contact email not found - Attribute not found - Category id not found - Invalid parameters passed - Record(s) for identifier not found - Returned when query params are invalid - Returned when invalid data posted - Feed not found - Campaign ID not found - api-key not found - DMARC policy requires domain authentication - DNS records not properly configured - Invalid OTP code provided - OTP code has expired - Domain already exists in your account - The sum of all IP weights must equal 100 - Authentication failed - Insufficient credits - Request already processed description: Error code displayed in case of a failure title: CrmDealsGetResponsesContentApplicationJsonSchemaCode Deals_importDealsCreationAndUpdation_Response_200: type: object properties: processId: type: integer description: The ID of the import process title: Deals_importDealsCreationAndUpdation_Response_200 GetPipelineStagesRequestBadRequestError: type: object properties: code: $ref: '#/components/schemas/CrmPipelineDetailsGetResponsesContentApplicationJsonSchemaCode' description: Error code displayed in case of a failure message: type: string description: Readable message associated to the failure required: - code - message title: GetPipelineStagesRequestBadRequestError CrmAttributesDealsGetResponsesContentApplicationJsonSchemaCode: type: string enum: - invalid_parameter - missing_parameter - out_of_range - campaign_processing - campaign_sent - document_not_found - not_enough_credits - permission_denied - duplicate_parameter - duplicate_request - method_not_allowed - unauthorized - account_under_validation - not_acceptable - bad_request - unprocessable_entity - Domain does not exist - Contact email not found - Attribute not found - Category id not found - Invalid parameters passed - Record(s) for identifier not found - Returned when query params are invalid - Returned when invalid data posted - Feed not found - Campaign ID not found - api-key not found - DMARC policy requires domain authentication - DNS records not properly configured - Invalid OTP code provided - OTP code has expired - Domain already exists in your account - The sum of all IP weights must equal 100 - Authentication failed - Insufficient credits - Request already processed description: Error code displayed in case of a failure title: CrmAttributesDealsGetResponsesContentApplicationJsonSchemaCode CrmDealsGetParametersSort: type: string enum: - asc - desc title: CrmDealsGetParametersSort CrmDealsIdPatchRequestBodyContentApplicationJsonSchemaAttributes: type: object properties: {} description: 'Attributes for deal update To assign owner of a Deal you can send attributes.deal_owner and utilize the account email or ID. If you wish to update the pipeline of a deal you need to provide the `pipeline` and the `deal_stage` Pipeline and deal_stage are ids you can fetch using this endpoint `/crm/pipeline/details/{pipelineID}` ' title: CrmDealsIdPatchRequestBodyContentApplicationJsonSchemaAttributes Deals_createADeal_Response_201: type: object properties: id: type: string description: Unique deal id required: - id description: Created deal id title: Deals_createADeal_Response_201 UpdateADealRequestBadRequestError: type: object properties: code: $ref: '#/components/schemas/CrmDealsIdPatchResponsesContentApplicationJsonSchemaCode' description: Error code displayed in case of a failure message: type: string description: Readable message associated to the failure required: - code - message title: UpdateADealRequestBadRequestError CrmPipelineDetailsGetResponsesContentApplicationJsonSchemaCode: type: string enum: - invalid_parameter - missing_parameter - out_of_range - campaign_processing - campaign_sent - document_not_found - not_enough_credits - permission_denied - duplicate_parameter - duplicate_request - method_not_allowed - unauthorized - account_under_validation - not_acceptable - bad_request - unprocessable_entity - Domain does not exist - Contact email not found - Attribute not found - Category id not found - Invalid parameters passed - Record(s) for identifier not found - Returned when query params are invalid - Returned when invalid data posted - Feed not found - Campaign ID not found - api-key not found - DMARC policy requires domain authentication - DNS records not properly configured - Invalid OTP code provided - OTP code has expired - Domain already exists in your account - The sum of all IP weights must equal 100 - Authentication failed - Insufficient credits - Request already processed description: Error code displayed in case of a failure title: CrmPipelineDetailsGetResponsesContentApplicationJsonSchemaCode DealAttributes: type: object properties: {} description: Deal attributes with values title: DealAttributes CrmDealsImportPostRequestBodyContentMultipartFormDataSchemaMapping: type: object properties: {} description: "The mapping options in JSON format. Here is an example of the JSON structure: ```json {\n \"link_entities\": true, // Determines whether to link related entities during the import process\n \"unlink_entities\": false, // Determines whether to unlink related entities during the import process\n \"update_existing_records\": true, // Determines whether to update based on deal ID or treat every row as create\n \"unset_empty_attributes\": false // Determines whether to unset a specific attribute during update if the values input is blank\n} ```\n" title: CrmDealsImportPostRequestBodyContentMultipartFormDataSchemaMapping 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 Deal: type: object properties: id: type: string description: Unique deal id attributes: $ref: '#/components/schemas/DealAttributes' description: Deal attributes with values linkedContactsIds: type: array items: type: integer description: Contact ids for contacts linked to this deal linkedCompaniesIds: type: array items: type: string description: Companies ids for companies linked to this deal description: Deal Details title: Deal CrmDealsPostRequestBodyContentApplicationJsonSchemaAttributes: type: object properties: {} 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}` ' title: CrmDealsPostRequestBodyContentApplicationJsonSchemaAttributes ImportDealsCreationAndUpdationRequestBadRequestError: type: object properties: message: type: string title: ImportDealsCreationAndUpdationRequestBadRequestError CrmAttributesDealsGetResponsesContentApplicationJsonSchemaItems: type: object properties: internalName: type: string description: Internal name of the attribute attributeTypeName: type: string description: Type of the attribute label: type: string description: Display label of the attribute attributeOptions: type: array items: $ref: '#/components/schemas/CrmAttributesDealsGetResponsesContentApplicationJsonSchemaItemsAttributeOptionsItems' description: Options for single-select or multi-choice attributes isRequired: type: boolean description: Whether this attribute is required isValueReadonly: type: boolean description: Whether this attribute value is read-only description: Deal attribute details title: CrmAttributesDealsGetResponsesContentApplicationJsonSchemaItems Deals_getAllDeals_Response_200: type: object properties: items: type: array items: $ref: '#/components/schemas/Deal' description: List of deals description: List of Deals title: Deals_getAllDeals_Response_200 Pipelines: type: array items: $ref: '#/components/schemas/Pipeline' description: List of pipeline title: Pipelines GetAllDealsRequestBadRequestError: type: object properties: code: $ref: '#/components/schemas/CrmDealsGetResponsesContentApplicationJsonSchemaCode' description: Error code displayed in case of a failure message: type: string description: Readable message associated to the failure required: - code - message title: GetAllDealsRequestBadRequestError CrmDealsIdPatchResponsesContentApplicationJsonSchemaCode: type: string enum: - invalid_parameter - missing_parameter - out_of_range - campaign_processing - campaign_sent - document_not_found - not_enough_credits - permission_denied - duplicate_parameter - duplicate_request - method_not_allowed - unauthorized - account_under_validation - not_acceptable - bad_request - unprocessable_entity - Domain does not exist - Contact email not found - Attribute not found - Category id not found - Invalid parameters passed - Record(s) for identifier not found - Returned when query params are invalid - Returned when invalid data posted - Feed not found - Campaign ID not found - api-key not found - DMARC policy requires domain authentication - DNS records not properly configured - Invalid OTP code provided - OTP code has expired - Domain already exists in your account - The sum of all IP weights must equal 100 - Authentication failed - Insufficient credits - Request already processed description: Error code displayed in case of a failure title: CrmDealsIdPatchResponsesContentApplicationJsonSchemaCode PipelineStagesItems: type: object properties: id: type: string description: Stage id name: type: string description: Stage name description: Stage details title: PipelineStagesItems GetDealAttributesRequestBadRequestError: type: object properties: code: $ref: '#/components/schemas/CrmAttributesDealsGetResponsesContentApplicationJsonSchemaCode' description: Error code displayed in case of a failure message: type: string description: Readable message associated to the failure required: - code - message title: GetDealAttributesRequestBadRequestError 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.