---
title: "Handle Inbound Call"
method: POST
path: "/crm/extensions/calling/2026-09/inbound-call"
tags: ["Advanced"]
---

# Handle Inbound Call

`POST /crm/extensions/calling/2026-09/inbound-call`

## Request

- Base URL: `https://api.hubapi.com`
- URL: `https://api.hubapi.com/crm/extensions/calling/2026-09/inbound-call`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.highly_sensitive.write.v2`
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.write`
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.sensitive.write.v2`
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.schemas.contacts.write`

This endpoint processes inbound calls by accepting a request with details about the call. It requires a JSON payload containing information such as the call's external ID, final status, and phone numbers involved. This operation is useful for integrating third-party call data into HubSpot, allowing for seamless tracking and management of inbound calls.

## Request body

- CompletedThirdPartyCallRequest
  - `callStartedTimestamp` string, date-time: The date and time when the call started, in ISO 8601 format.
  - `createEngagement` boolean, required: A boolean indicating whether an engagement should be created for this call.
  - `durationSeconds` integer: The duration of the call in seconds, represented as an integer.
  - `engagementProperties` object, required: A map of custom property names to their values, used to store additional information about the engagement.
  - `externalCallId` string, required: A unique identifier for the call provided by the external system.
  - `finalCallStatus` 'BUSY' | 'CALLING_CRM_USER' | 'CANCELED' | 'COMPLETED' | 'CONNECTING' | 'FAILED' | 'HOLD' | 'IN_PROGRESS' | 'MISSED' | 'NO_ANSWER' | 'QUEUED' | 'RINGING' | 'UNKNOWN', required: The final status of the call. Valid values include 'QUEUED', 'RINGING', 'IN_PROGRESS', 'CANCELED', 'COMPLETED', 'BUSY', 'FAILED', 'NO_ANSWER', 'CONNECTING', 'CALLING_CRM_USER', 'MISSED', 'HOLD', and 'UNKNOWN'.
  - `fromNumber` FormattedPhoneNumber, required
    - `e164Number` string, required: The phone number formatted in E.164 standard, which includes the country code and the subscriber number as a string.
    - `extension` string: An optional string representing the extension number associated with the phone number.
    - `phoneNumberType` 'FIXED_LINE' | 'FIXED_LINE_OR_MOBILE' | 'MOBILE' | 'PAGER' | 'PERSONAL_NUMBER' | 'PREMIUM_RATE' | 'SHARED_COST' | 'TOLL_FREE' | 'UAN' | 'UNKNOWN' | 'VOICEMAIL' | 'VOIP', required: The type of phone number, represented as a string. Valid values include 'FIXED_LINE', 'MOBILE', 'FIXED_LINE_OR_MOBILE', 'TOLL_FREE', 'PREMIUM_RATE', 'SHARED_COST', 'VOIP', 'PERSONAL_NUMBER', 'PAGER', 'UAN', 'VOICEMAIL', and 'UNKNOWN'.
  - `potentialRecipientUserIds` integer[], required: An array of integers representing the user IDs of potential recipients of the call.
  - `toNumber` FormattedPhoneNumber, required
    - `e164Number` string, required: The phone number formatted in E.164 standard, which includes the country code and the subscriber number as a string.
    - `extension` string: An optional string representing the extension number associated with the phone number.
    - `phoneNumberType` 'FIXED_LINE' | 'FIXED_LINE_OR_MOBILE' | 'MOBILE' | 'PAGER' | 'PERSONAL_NUMBER' | 'PREMIUM_RATE' | 'SHARED_COST' | 'TOLL_FREE' | 'UAN' | 'UNKNOWN' | 'VOICEMAIL' | 'VOIP', required: The type of phone number, represented as a string. Valid values include 'FIXED_LINE', 'MOBILE', 'FIXED_LINE_OR_MOBILE', 'TOLL_FREE', 'PREMIUM_RATE', 'SHARED_COST', 'VOIP', 'PERSONAL_NUMBER', 'PAGER', 'UAN', 'VOICEMAIL', and 'UNKNOWN'.
  - `userId` integer: The unique identifier of the user associated with the call. This is an integer.

## Response `200`

successful operation

- CompletedThirdPartyCallResponse
  - `callerIdMatches` union[], required: An array containing information about the caller ID matches. Each item in the array can be either a ContactCallerId or a CompanyCallerId object.
    - union
      - ContactCallerId
        - `callerIdType` 'CONTACT', required: A string indicating the type of caller ID, which is 'CONTACT' by default.
        - `email` string: The email address of the contact, represented as a string.
        - `firstName` string: The first name of the contact, represented as a string.
        - `lastName` string: The last name of the contact, represented as a string.
        - `objectCoordinates` ObjectCoordinates, required
          - `objectId` integer, required: The unique identifier for the object. It is an integer formatted as int64.
          - `objectTypeId` string, required: The identifier for the type of object. It is a string.
          - `portalId` integer, required: The unique identifier for the HubSpot portal. It is an integer.
      - CompanyCallerId
        - `callerIdType` 'COMPANY', required: A string representing the type of caller ID. The only valid value is 'COMPANY'.
        - `name` string: A string representing the name associated with the company caller ID.
        - `objectCoordinates` ObjectCoordinates, required
          - `objectId` integer, required: The unique identifier for the object. It is an integer formatted as int64.
          - `objectTypeId` string, required: The identifier for the type of object. It is a string.
          - `portalId` integer, required: The unique identifier for the HubSpot portal. It is an integer.

## Other responses

- `default`: An error occurred.

## Changes

- **2026-10-10** (2026-09) `278a6bf84db7`: 2 info
  - the security scope `crm.objects.contacts.highly_sensitive.write.v2` was added to the endpoint's security scheme `oauth2`
  - the security scope `crm.schemas.contacts.write` was removed from the endpoint's security scheme `oauth2`
- **2026-09-09** (2026-09) `e9a241bb75d3`: 2 info
  - the security scope `crm.objects.contacts.highly_sensitive.write.v2` was added to the endpoint's security scheme `oauth2`
  - the security scope `crm.schemas.contacts.write` was removed from the endpoint's security scheme `oauth2`
- **2026-09-03** (2026-09) `64287a925cab`: 2 breaking, 9 info
  - the `callerIdMatches/items/oneOf[subschema #1: CONTACT]/objectCoordinates/objectId` response's property format changed from `int32` to `int64` for status `200`
  - the `callerIdMatches/items/oneOf[subschema #2: COMPANY]/objectCoordinates/objectId` response's property format changed from `int32` to `int64` for status `200`
  - the endpoint scheme security `private_apps` was removed from the API
  - the endpoint scheme security `private_apps` was removed from the API
  - …7 more

[Operation history](https://skmtc.dev/hubspot/apis/crm-transcriptions/changes/crm/extensions/calling/2026-09/inbound-call/post.md)

---

[API](https://skmtc.dev/hubspot/apis/crm-transcriptions.md) - [All operations](https://skmtc.dev/hubspot/apis/crm-transcriptions/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/crm-transcriptions/revisions/278a6bf84db7?raw)