Ignorar e ir ao conteúdo principal

Use the engagements API to manage notes, emails, tasks, meetings, and calls on CRM records.

You want to upgrade your integration to log calls and meetings to contact records to streamline the sales process.

Guia relacionado:

Engagements overview

GET

/engagements/v1/engagements/:engagementId

This endpoint is used to get an engagement (a task or activity) for a CRM record in HubSpot.

Use case for this endpoint: This data can be used to report on per-rep productivity or to integrate HubSpot with other back-office tools.

For another example, you can use this information about an individual call to drive automation about when the next follow-up meeting or call should happen.

In addition to the contacts scope, the sales-email-read scope is required in order to receive the details of any email-type engagements. See the Engagement API Overview for more details.

Requisitos
Escopos
  1. crm.objects.companies.read
  2. crm.objects.contacts.read
  3. crm.objects.deals.read
  4. tickets
  5. e-commerce
Métodos de autenticação

Aplicativos privados

OAuth

Parâmetros
engagementId*

Parâm. de caminho

The unique ID of the engagement you want the information for.

Resposta

Mostrar mais

GET

/engagements/v1/engagements/paged

This endpoint is used to get all engagements in an account.

Use case for this endpoint: Because engagements represent individual activity, you can use the endpoint to source the inputs for a machine learning model to help predict the best time for a call to a prospect or a customer.

In addition to the contacts scope, the sales-email-read scope is required to receive the details of any email-type engagements. See the Engagements API Overview for more details.

Requisitos
Escopos
  1. crm.objects.companies.read
  2. crm.objects.contacts.read
  3. crm.objects.deals.read
  4. tickets
  5. e-commerce
Métodos de autenticação

Aplicativos privados

OAuth

Parâmetros
limit

Param. de consulta

The number of records to return. Defaults to 100, has a maximum value of 250.

offset

Param. de consulta

Used to page through the results. If there are more records in your portal than the limit= parameter, you will need to use the offset returned in the first request to get the next set of results.

Resposta

Mostrar mais

Returns a paginated set of engagements. Up to 250 records can be returned in a single response.

In addition to the list of engagements, each request will also return two values, offset and hasMore. If hasMore is true, you'll need to make another request, using the offset to get the next page of engagement records.

This endpoint will not return engagements for sample contacts "Brian Halligan" or "Cool Robot."

GET

/engagements/v1/engagements/recent/modified

Get the most recently created or updated engagements in a portal, sorted by when they were last updated, with the most recently updated engagements first.

Note: This endpoint will only return records updated in the last 30 days, or the 10k most recently updated records. If you need to get all of your engagements, please use this endpoint.

Note: In addition to the contacts scope, the sales-email-read scope is required in order to receive the details of any email type engagements. See the Engagements overview for more details.

Requisitos
Escopos
  1. crm.objects.companies.read
  2. crm.objects.contacts.read
  3. crm.objects.deals.read
  4. tickets
  5. e-commerce
Métodos de autenticação

Aplicativos privados

OAuth

Parâmetros
count

Param. de consulta

The number of items to include in the response. Defaults to 20, has a maximum value of 100.

offset

Param. de consulta

Used to page through the recent engagements. Each response will include an offset value that can be used with this parmaeter to get the next set of records.

since

Param. de consulta

A Unix timestamp in milliseconds. If this parameter is included, only records modified after the specified time will be returned.

Resposta

Mostrar mais

GET

/calling/v1/dispositions

Get all possible dispositions for sales calls (stored as engagements), listed as the outcome when viewing the call's outcome when viewing the call in the timeline in HubSpot.

Requisitos
Escopos
  1. crm.objects.companies.read
  2. crm.objects.contacts.read
  3. crm.objects.deals.read
  4. tickets
  5. e-commerce
Métodos de autenticação

Aplicativos privados

OAuth

Parâmetros

Esse ponto de extremidade não aceita nenhum parâmetro.

Resposta

Mostrar mais

POST

/engagements/v1/engagements

Use this endpoint to create an engagement (an email, call, meeting, task or note) on an object in HubSpot.

Use case for this endpoint: This endpoint is useful for keeping your CRM records up-to-date on any interactions that take place outside of HubSpot. Activity reporting in the CRM also feeds off of this data.

You can associate engagements with objects to ensure they're displayed correctly in the UI. (See example request body to the right.)

Tasks created through HubSpot's API will not trigger user notifications.

For note-type engagements, the body of the note will be limited to 65536 characters.

Requisitos
Escopos
  1. crm.objects.companies.write
  2. crm.objects.contacts.write
  3. crm.objects.deals.write
  4. tickets
  5. e-commerce
Métodos de autenticação

Aplicativos privados

OAuth

Parâmetros
type*

Parâm. de corpo

One of: EMAIL, CALL, MEETING, TASK, NOTE

metadata*

Parâm. de corpo

An object representing the details of the engagement. See the examples to the right for details about the format of the metadata for specific engagement types.

ownerId

Parâm. de corpo

Corresponding to an Owner. Task engagements use the ownerId to populate the Assigned to field.

timestamp

Parâm. de corpo

Timestamp (in milliseconds). This timestamp will be treated as the time that the engagement happened, and will determine where the engagement appears in the timeline for any associated records.

Resposta

Mostrar mais
  • If the request is successful, returns a 200 response with the JSON of the new engagement.
  • If the request is unsuccessful, returns a 4xx response with error details.

PATCH

/engagements/v1/engagements/:engagementId

Update an engagement (a task or activity) on an object in HubSpot.

See the documentation for creating an engagement for more details on the fields that can be included.

Note: Associations cannot be modified using this endpoint. Use the CRM associations API to update associations for existing engagements.

Requisitos
Escopos
  1. crm.objects.companies.write
  2. crm.objects.contacts.write
  3. crm.objects.deals.write
  4. tickets
  5. e-commerce
Métodos de autenticação

Aplicativos privados

OAuth

Parâmetros
Engagement JSON*

Parâm. de corpo

An object representing the engagement you have created.

Resposta

Mostrar mais

DELETE

/engagements/v1/engagements/:engagementId

Delete an engagement (a task or activity) on an object in HubSpot.

Example URL to DELETE to: api.hubapi.com/engagements/v1/engagements/74

Requisitos
Escopos
  1. crm.objects.companies.write
  2. crm.objects.contacts.write
  3. crm.objects.deals.write
  4. tickets
  5. e-commerce
Métodos de autenticação

Aplicativos privados

OAuth

Parâmetros
engagementId*

Parâm. de caminho

The unique ID of the engagement you want to delete.

Resposta

Mostrar mais