Actions

The ballerinax/hubspot.crm.engagements.calls package exposes the following clients:

Client	Purpose
Client	Manage HubSpot call engagement records: CRUD, batch operations, and search.

---

Client

Manage HubSpot call engagement records: CRUD, batch operations, and search.

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig	Required	Authentication configuration: OAuth 2.0 refresh token, bearer token, or API keys.
httpVersion	http:HttpVersion	HTTP_2_0	HTTP protocol version.
timeout	decimal	30	Request timeout in seconds.
retryConfig	http:RetryConfig	()	Retry configuration for failed requests.
secureSocket	http:ClientSecureSocket	()	SSL/TLS configuration.
proxy	http:ProxyConfig	()	Proxy server configuration.
circuitBreaker	http:CircuitBreakerConfig	()	Circuit breaker configuration for fault tolerance.
compression	http:Compression	COMPRESSION_AUTO	HTTP compression configuration.
validation	boolean	true	Enable or disable payload validation.

Initializing the client

import ballerinax/hubspot.crm.engagements.calls;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

calls:Client callsClient = check new ({
    auth: {
        clientId: clientId,
        clientSecret: clientSecret,
        refreshToken: refreshToken,
        refreshUrl: "https://api.hubapi.com/oauth/v1/token"
    }
});

Operations

Call CRUD

Retrieve calls

Signature: get /

Retrieves a page of call engagement records with optional filtering by properties, associations, and pagination.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetCrmV3ObjectsCallsGetPageQueries	No	Query parameters including limit, after, properties, associations, and archived.

Returns: CollectionResponseSimplePublicObjectWithAssociationsForwardPaging|error

Sample code:

calls:CollectionResponseSimplePublicObjectWithAssociationsForwardPaging response =
    check callsClient->/.get();

Sample response:

{
  "results": [
    {
      "id": "48093927432",
      "properties": {
        "hs_createdate": "2025-01-15T10:30:00.000Z",
        "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z",
        "hs_object_id": "48093927432",
        "hs_call_title": "Discovery Call"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "48093927432",
      "link": "https://api.hubapi.com/crm/v3/objects/calls?after=48093927432"
    }
  }
}

Create a call

Signature: post /

Creates a new call engagement record with the specified properties and optional associations.

Parameters:

Name	Type	Required	Description
payload	SimplePublicObjectInputForCreate	Yes	Call properties and optional associations.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: SimplePublicObject|error

Sample code:

calls:SimplePublicObject response = check callsClient->/.post({
    properties: {
        "hs_timestamp": "2025-01-15T10:30:00.000Z",
        "hs_call_title": "Discovery Call",
        "hs_call_body": "Discussed product requirements and timeline.",
        "hs_call_duration": "360000",
        "hs_call_from_number": "+1234567890",
        "hs_call_to_number": "+0987654321",
        "hs_call_status": "COMPLETED"
    },
    associations: [
        {
            types: [
                {
                    associationCategory: "HUBSPOT_DEFINED",
                    associationTypeId: 194
                }
            ],
            to: {
                id: "12345"
            }
        }
    ]
});

Sample response:

{
  "id": "48093927432",
  "properties": {
    "hs_timestamp": "2025-01-15T10:30:00.000Z",
    "hs_call_title": "Discovery Call",
    "hs_call_body": "Discussed product requirements and timeline.",
    "hs_call_duration": "360000",
    "hs_call_from_number": "+1234567890",
    "hs_call_to_number": "+0987654321",
    "hs_call_status": "COMPLETED",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z",
    "hs_object_id": "48093927432"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Retrieve a call

Signature: get /[string callId]

Retrieves a single call engagement record by its ID, with optional property and association details.

Parameters:

Name	Type	Required	Description
callId	string	Yes	The ID of the call to retrieve.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	GetCrmV3ObjectsCallsCallIdGetByIdQueries	No	Query parameters including properties, associations, and archived.

Returns: SimplePublicObjectWithAssociations|error

Sample code:

calls:SimplePublicObjectWithAssociations response =
    check callsClient->/["48093927432"].get();

Sample response:

{
  "id": "48093927432",
  "properties": {
    "hs_timestamp": "2025-01-15T10:30:00.000Z",
    "hs_call_title": "Discovery Call",
    "hs_call_body": "Discussed product requirements and timeline.",
    "hs_call_duration": "360000",
    "hs_call_status": "COMPLETED",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z",
    "hs_object_id": "48093927432"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Update a call

Signature: patch /[string callId]

Updates the properties of an existing call engagement record.

Parameters:

Name	Type	Required	Description
callId	string	Yes	The ID of the call to update.
payload	SimplePublicObjectInput	Yes	Properties to update.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	PatchCrmV3ObjectsCallsCallIdUpdateQueries	No	Query parameters including idProperty.

Returns: SimplePublicObject|error

Sample code:

calls:SimplePublicObject response = check callsClient->/["48093927432"].patch({
    properties: {
        "hs_call_title": "Updated Discovery Call",
        "hs_call_status": "COMPLETED"
    }
});

Sample response:

{
  "id": "48093927432",
  "properties": {
    "hs_call_title": "Updated Discovery Call",
    "hs_call_status": "COMPLETED",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T11:00:00.000Z",
    "hs_object_id": "48093927432"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T11:00:00.000Z",
  "archived": false
}

Archive a call

Signature: delete /[string callId]

Archives (soft-deletes) a call engagement record by its ID.

Parameters:

Name	Type	Required	Description
callId	string	Yes	The ID of the call to archive.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: error?

Sample code:

check callsClient->/["48093927432"].delete();

Batch operations

Create a batch of calls

Signature: post /batch/create

Creates multiple call engagement records in a single request.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectInputForCreate	Yes	Batch of call inputs with properties and optional associations.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

calls:BatchResponseSimplePublicObject|calls:BatchResponseSimplePublicObjectWithErrors response =
    check callsClient->/batch/create.post({
        inputs: [
            {
                properties: {
                    "hs_timestamp": "2025-01-15T10:30:00.000Z",
                    "hs_call_title": "Call 1",
                    "hs_call_status": "COMPLETED"
                },
                associations: []
            },
            {
                properties: {
                    "hs_timestamp": "2025-01-15T11:00:00.000Z",
                    "hs_call_title": "Call 2",
                    "hs_call_status": "COMPLETED"
                },
                associations: []
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "48093927432",
      "properties": {
        "hs_call_title": "Call 1",
        "hs_call_status": "COMPLETED",
        "hs_createdate": "2025-01-15T10:30:00.000Z",
        "hs_object_id": "48093927432"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    },
    {
      "id": "48093927433",
      "properties": {
        "hs_call_title": "Call 2",
        "hs_call_status": "COMPLETED",
        "hs_createdate": "2025-01-15T11:00:00.000Z",
        "hs_object_id": "48093927433"
      },
      "createdAt": "2025-01-15T11:00:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T10:30:00.000Z",
  "completedAt": "2025-01-15T10:30:01.000Z"
}

Retrieve a batch of calls

Signature: post /batch/read

Retrieves multiple call engagement records by their IDs in a single request.

Parameters:

Name	Type	Required	Description
payload	BatchReadInputSimplePublicObjectId	Yes	Batch of call IDs to retrieve, with optional property selection.
headers	map<string|string[]>	No	Optional HTTP headers.
queries	PostCrmV3ObjectsCallsBatchReadReadQueries	No	Query parameters including archived.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

calls:BatchResponseSimplePublicObject|calls:BatchResponseSimplePublicObjectWithErrors response =
    check callsClient->/batch/read.post({
        inputs: [
            { id: "48093927432" },
            { id: "48093927433" }
        ],
        properties: ["hs_call_title", "hs_call_status", "hs_call_duration"]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "48093927432",
      "properties": {
        "hs_call_title": "Call 1",
        "hs_call_status": "COMPLETED",
        "hs_call_duration": "360000"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    },
    {
      "id": "48093927433",
      "properties": {
        "hs_call_title": "Call 2",
        "hs_call_status": "COMPLETED",
        "hs_call_duration": "180000"
      },
      "createdAt": "2025-01-15T11:00:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T10:30:00.000Z",
  "completedAt": "2025-01-15T10:30:01.000Z"
}

Update a batch of calls

Signature: post /batch/update

Updates properties on multiple call engagement records in a single request.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectBatchInput	Yes	Batch of call IDs with updated properties.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

calls:BatchResponseSimplePublicObject|calls:BatchResponseSimplePublicObjectWithErrors response =
    check callsClient->/batch/update.post({
        inputs: [
            {
                id: "48093927432",
                properties: {
                    "hs_call_title": "Updated Call 1",
                    "hs_call_status": "COMPLETED"
                }
            },
            {
                id: "48093927433",
                properties: {
                    "hs_call_title": "Updated Call 2",
                    "hs_call_status": "COMPLETED"
                }
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "48093927432",
      "properties": {
        "hs_call_title": "Updated Call 1",
        "hs_call_status": "COMPLETED",
        "hs_lastmodifieddate": "2025-01-15T11:00:00.000Z"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z",
      "archived": false
    },
    {
      "id": "48093927433",
      "properties": {
        "hs_call_title": "Updated Call 2",
        "hs_call_status": "COMPLETED",
        "hs_lastmodifieddate": "2025-01-15T11:00:00.000Z"
      },
      "createdAt": "2025-01-15T11:00:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T11:00:00.000Z",
  "completedAt": "2025-01-15T11:00:01.000Z"
}

Archive a batch of calls

Signature: post /batch/archive

Archives (soft-deletes) multiple call engagement records in a single request.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectId	Yes	Batch of call IDs to archive.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: error?

Sample code:

check callsClient->/batch/archive.post({
    inputs: [
        { id: "48093927432" },
        { id: "48093927433" }
    ]
});

Create or update a batch of calls by unique property

Signature: post /batch/upsert

Creates or updates multiple call records in a single request, matching by a unique property value.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectBatchInputUpsert	Yes	Batch of call inputs with an idProperty for matching and properties to set.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: BatchResponseSimplePublicUpsertObject|BatchResponseSimplePublicUpsertObjectWithErrors|error

Sample code:

calls:BatchResponseSimplePublicUpsertObject|calls:BatchResponseSimplePublicUpsertObjectWithErrors response =
    check callsClient->/batch/upsert.post({
        inputs: [
            {
                idProperty: "hs_object_id",
                id: "48093927432",
                properties: {
                    "hs_call_title": "Upserted Call",
                    "hs_call_status": "COMPLETED"
                }
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "48093927432",
      "properties": {
        "hs_call_title": "Upserted Call",
        "hs_call_status": "COMPLETED"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T11:30:00.000Z",
      "archived": false,
      "new": false
    }
  ],
  "startedAt": "2025-01-15T11:30:00.000Z",
  "completedAt": "2025-01-15T11:30:01.000Z"
}

Search

Search for calls

Signature: post /search

Searches for call engagement records using filters, property conditions, and sorting criteria.

Parameters:

Name	Type	Required	Description
payload	PublicObjectSearchRequest	Yes	Search request with filter groups, sorting, properties to return, and pagination.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CollectionResponseWithTotalSimplePublicObjectForwardPaging|error

Sample code:

calls:CollectionResponseWithTotalSimplePublicObjectForwardPaging response =
    check callsClient->/search.post({
        filterGroups: [
            {
                filters: [
                    {
                        propertyName: "hs_call_status",
                        operator: "EQ",
                        value: "COMPLETED"
                    }
                ]
            }
        ],
        properties: ["hs_call_title", "hs_call_status", "hs_call_duration"],
        sorts: ["hs_createdate"],
        limit: 10
    });

Sample response:

{
  "total": 2,
  "results": [
    {
      "id": "48093927432",
      "properties": {
        "hs_call_title": "Discovery Call",
        "hs_call_status": "COMPLETED",
        "hs_call_duration": "360000"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    },
    {
      "id": "48093927433",
      "properties": {
        "hs_call_title": "Follow-up Call",
        "hs_call_status": "COMPLETED",
        "hs_call_duration": "180000"
      },
      "createdAt": "2025-01-15T11:00:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "48093927433"
    }
  }
}