Detalhes do engajamento
Essa API é estável, mas usa um formato antigo. Isso significa que algumas funcionalidades podem não estar disponíveis (por exemplo, chamadas de teste e integração Postman).
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.
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
crm.objects.companies.read
crm.objects.contacts.read
crm.objects.deals.read
tickets
e-commerce
Parâmetros
The unique ID of the engagement you want the information for.
Resposta
Example GET URL:
https://api.hubapi.com/engagements/v1/engagements/1778115327
You will receive an object representing the requested engagement:
{
"engagement": {
"id": 562,
"portalId": 18770,
"active": true,
"createdAt": 1409172644778,
"lastUpdated": 1409172644778,
"ownerId": 1,
"type": "NOTE",
"timestamp": 1409172644778
},
"associations": {
"contactIds": [
2
],
"companyIds": [],
"dealIds": [],
"ownerIds": []
},
"metadata": {
"body": "note body"
}
}
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
crm.objects.companies.read
crm.objects.contacts.read
crm.objects.deals.read
tickets
e-commerce
Parâmetros
The number of records to return. Defaults to 100, has a maximum value of 250.
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
xxxxxxxxxx
Example GET URL:
https://api.hubapi.com/engagements/v1/engagements/paged?limit=2
{
"results": [
{
"engagement": {
"id": 29090716,
"portalId": 62515,
"active": true,
"createdAt": 1444223400781,
"lastUpdated": 1444223400781,
"createdBy": 215482,
"modifiedBy": 215482,
"ownerId": 70,
"type": "NOTE",
"timestamp": 1444223400781
},
"associations": {
"contactIds": [
247
],
"companyIds": [
],
"dealIds": [
],
"ownerIds": [
],
"workflowIds": [
]
},
"attachments": [
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
crm.objects.companies.read
crm.objects.contacts.read
crm.objects.deals.read
tickets
e-commerce
Parâmetros
The number of items to include in the response. Defaults to 20, has a maximum value of 100.
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.
A Unix timestamp in milliseconds. If this parameter is included, only records modified after the specified time will be returned.
Resposta
xxxxxxxxxx
Example GET URL:
https://api.hubapi.com/engagements/v1/engagements/recent/modified?count=2&since=1483246800000
Example response:
{
"results": [
{
"engagement": {
"id": 420584370,
"portalId": 62515,
"active": true,
"createdAt": 1501099545265,
"lastUpdated": 1501099545265,
"createdBy": 12345,
"modifiedBy": 12345,
"type": "CALL",
"timestamp": 1501099530663
},
"associations": {
"contactIds": [
],
"companyIds": [
],
"dealIds": [
178905506
],
"ownerIds": [
],
"workflowIds": [
],
"ticketIds": [
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.
Please note: due to how the underlying redirect logic works, your API logs
will show any calls to this endpoint as /twilio/v1/dispositions
.
Requisitos
crm.objects.companies.read
crm.objects.contacts.read
crm.objects.deals.read
tickets
e-commerce
Parâmetros
Resposta
xxxxxxxxxx
Example GET URL:
https://api.hubapi.com/calling/v1/dispositions
Example JSON response:
[
{
"id": "73a0d17f-1163-4015-bdd5-ec830791da20",
"label": "No answer"
},
{
"id": "9d9162e7-6cf3-4944-bf63-4dff82258764",
"label": "Busy"
},
{
"id": "17b47fee-58de-441e-a44c-c6300d46f273",
"label": "Wrong number"
},
{
"id": "a4c4c377-d246-4b32-a13b-75a56a4cd0ff",
"label": "Left live message"
},
{
"id": "b2cf5968-551e-4856-9783-52b3da59a7d0",
"label": "Left voicemail"
},
{
"id": "f240bbac-87c9-4f6e-bf70-924b57d47db7",
"label": "Connected"
}
]
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
crm.objects.companies.write
crm.objects.contacts.write
crm.objects.deals.write
tickets
e-commerce
Parâmetros
One of: EMAIL
, CALL
, MEETING
, TASK
, NOTE
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.
Corresponding to an Owner. Task engagements use the ownerId to populate the Assigned to field.
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
xxxxxxxxxx
Example POST URL:
https://api.hubapi.com/engagements/v1/engagements
Example POST body (this example is for a NOTE engagement):
{
"engagement": {
"active": true,
"ownerId": 1,
"type": "NOTE",
"timestamp": 1409172644778
},
"associations": {
"contactIds": [2],
"companyIds": [ ],
"dealIds": [ ],
"ownerIds": [ ],
"ticketIds":[ ]
},
"attachments": [
{
"id": 4241968539
}
],
"metadata": {
"body": "note body"
}
}
The optional "attachments" parameter accepts a list of file IDs, corresponding to IDs you get for files from the CMS Files API.
For email engagements, the type needs to be set to "EMAIL", and the metadata needs to have the following format:
"metadata": {
"from": {
"email": "email@domain.com",
"firstName": "First",
"lastName": "Last"
- 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
crm.objects.companies.write
crm.objects.contacts.write
crm.objects.deals.write
tickets
e-commerce
Parâmetros
An object representing the engagement you have created.
Resposta
xxxxxxxxxx
Example request body to PATCH:
{
"engagement": {
"ownerId": 1,
"timestamp": 1409172644778
},
"metadata": {
"body": "a new note body"
}
}
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
crm.objects.companies.write
crm.objects.contacts.write
crm.objects.deals.write
tickets
e-commerce
Parâmetros
The unique ID of the engagement you want to delete.
Resposta
xxxxxxxxxx
You will receive an object representing the requested engagement:
{
"engagement": {
"id": 562,
"portalId": 18770,
"active": true,
"createdAt": 1409172644778,
"lastUpdated": 1409172644778,
"ownerId": 1,
"type": "NOTE",
"timestamp": 1409172644778
},
"associations": {
"contactIds": [
2
],
"companyIds": [],
"dealIds": [],
"ownerIds": []
},
"metadata": {
"body": "note body"
}
}