Actions

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

Client	Purpose
Client	Manages HubSpot CRM lists, memberships, folders, search, and legacy ID mapping.

---

Client

Manages HubSpot CRM lists, memberships, folders, search, and legacy ID mapping.

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig	Required	OAuth 2.0 refresh token config, bearer token, or private app API key config.
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.
validation	boolean	true	Enable or disable constraint validation.
laxDataBinding	boolean	true	Enable or disable lax data binding.

Initializing the client

import ballerina/oauth2;
import ballerinax/hubspot.crm.lists as hslists;

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

hslists:OAuth2RefreshTokenGrantConfig auth = {
    clientId,
    clientSecret,
    refreshToken,
    credentialBearer: oauth2:POST_BODY_BEARER
};

final hslists:Client hubspotClient = check new ({auth});

Operations

List CRUD

Create a new list

Signature: post /

Creates a new list. The list can be MANUAL, DYNAMIC (filter-based), or SNAPSHOT.

Parameters:

Name	Type	Required	Description
payload	ListCreateRequest	Yes	List creation payload including objectTypeId, processingType, name, and optional filterBranch.
headers	map<string|string[]>	No	Custom headers.

Returns: ListCreateResponse|error

Sample code:

hslists:ListCreateResponse response = check hubspotClient->/.post({
    objectTypeId: "0-1",
    processingType: "MANUAL",
    name: "New Leads"
});

Sample response:

{
  "list": {
    "listId": "123456",
    "name": "New Leads",
    "objectTypeId": "0-1",
    "processingType": "MANUAL",
    "processingStatus": "COMPLETE",
    "listVersion": 1,
    "size": 0,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Fetch a list by ID

Signature: get /[string listId]

Fetches a list by its ILS ID. Optionally includes filter definitions.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the list to fetch.
queries	GetListIdGetByIdQueries	No	Query parameters. includeFilters (default false): whether to include filter branch details.
headers	map<string|string[]>	No	Custom headers.

Returns: ListFetchResponse|error

Sample code:

hslists:ListFetchResponse response = check hubspotClient->/["123456"].get();

Sample response:

{
  "list": {
    "listId": "123456",
    "name": "New Leads",
    "objectTypeId": "0-1",
    "processingType": "MANUAL",
    "processingStatus": "COMPLETE",
    "listVersion": 1,
    "size": 42,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-16T08:15:00.000Z"
  }
}

Fetch a list by name and object type

Signature: get /object-type-id/[string objectTypeId]/name/[string listName]

Fetches a list by its name and object type ID. The name match is not case sensitive.

Parameters:

Name	Type	Required	Description
objectTypeId	string	Yes	Object type ID (e.g., "0-1" for contacts, "0-5" for tickets).
listName	string	Yes	The name of the list to fetch.
queries	GetObjectTypeIdObjectTypeIdNameListNameGetByNameQueries	No	Query parameters. includeFilters (default false).
headers	map<string|string[]>	No	Custom headers.

Returns: ListFetchResponse|error

Sample code:

hslists:ListFetchResponse response = check hubspotClient->/"object-type-id"/["0-5"]/name/["High priority tickets"].get();

Sample response:

{
  "list": {
    "listId": "789012",
    "name": "High priority tickets",
    "objectTypeId": "0-5",
    "processingType": "DYNAMIC",
    "processingStatus": "COMPLETE",
    "listVersion": 3,
    "size": 15,
    "createdAt": "2025-01-10T09:00:00.000Z",
    "updatedAt": "2025-01-17T12:00:00.000Z"
  }
}

Fetch multiple lists by IDs

Signature: get /

Fetches multiple lists by their ILS IDs.

Parameters:

Name	Type	Required	Description
queries	GetGetAllQueries	No	Query parameters. listIds: array of list IDs to fetch. includeFilters (default false).
headers	map<string|string[]>	No	Custom headers.

Returns: ListsByIdResponse|error

Sample code:

hslists:ListsByIdResponse response = check hubspotClient->/.get(queries = {listIds: ["123456", "789012"]});

Sample response:

{
  "lists": [
    {"listId": "123456", "name": "New Leads", "objectTypeId": "0-1", "processingType": "MANUAL", "processingStatus": "COMPLETE", "listVersion": 1, "size": 42},
    {"listId": "789012", "name": "High priority tickets", "objectTypeId": "0-5", "processingType": "DYNAMIC", "processingStatus": "COMPLETE", "listVersion": 3, "size": 15}
  ]
}

Search lists

Signature: post /search

Searches for lists by name query, processing types, or list IDs with pagination.

Parameters:

Name	Type	Required	Description
payload	ListSearchRequest	Yes	Search parameters including query, processingTypes, listIds, offset, count, and sort.
headers	map<string|string[]>	No	Custom headers.

Returns: ListSearchResponse|error

Sample code:

hslists:ListSearchResponse response = check hubspotClient->/search.post({
    query: "Leads",
    count: 10,
    offset: 0
});

Sample response:

{
  "total": 2,
  "offset": 0,
  "hasMore": false,
  "lists": [
    {"listId": "123456", "name": "New Leads", "objectTypeId": "0-1", "processingType": "MANUAL", "size": 42},
    {"listId": "123457", "name": "Open Leads", "objectTypeId": "0-1", "processingType": "MANUAL", "size": 18}
  ]
}

Update a list name

Signature: put /[string listId]/update-list-name

Updates the name of an existing list.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the list to update.
queries	PutListIdUpdateListNameUpdateNameQueries	No	Query parameters. listName: the new name. includeFilters (default false).
headers	map<string|string[]>	No	Custom headers.

Returns: ListUpdateResponse|error

Sample code:

hslists:ListUpdateResponse response = check hubspotClient->/["123456"]/"update-list-name".put(queries = {listName: "Qualified Leads"});

Sample response:

{
  "updatedList": {
    "listId": "123456",
    "name": "Qualified Leads",
    "objectTypeId": "0-1",
    "processingType": "MANUAL",
    "processingStatus": "COMPLETE",
    "listVersion": 2,
    "size": 42
  }
}

Update list filter definition

Signature: put /[string listId]/update-list-filters

Updates the filter definition of a DYNAMIC list.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the list to update.
payload	ListFilterUpdateRequest	Yes	The new filter branch definition.
queries	PutListIdUpdateListFiltersUpdateListFiltersQueries	No	Query parameters. enrollObjectsInWorkflows (default false).
headers	map<string|string[]>	No	Custom headers.

Returns: ListUpdateResponse|error

Sample code:

hslists:ListFilterUpdateRequest payload = {
    filterBranch: {
        filterBranchType: "OR",
        filterBranchOperator: "OR",
        filterBranches: [{
            filterBranchType: "AND",
            filterBranchOperator: "AND",
            filterBranches: [],
            filters: [{
                filterType: "PROPERTY",
                property: "hs_ticket_priority",
                operation: {
                    operationType: "ENUMERATION",
                    operator: "IS_ANY_OF",
                    values: ["HIGH"],
                    includeObjectsWithNoValueSet: false
                }
            }]
        }],
        filters: []
    }
};
hslists:ListUpdateResponse response = check hubspotClient->/["789012"]/"update-list-filters".put(payload);

Sample response:

{
  "updatedList": {
    "listId": "789012",
    "name": "High priority tickets",
    "objectTypeId": "0-5",
    "processingType": "DYNAMIC",
    "processingStatus": "REFRESHING",
    "listVersion": 4,
    "size": 15
  }
}

Delete a list

Signature: delete /[string listId]

Deletes a list by its ILS ID. The list can be restored later.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the list to delete.
headers	map<string|string[]>	No	Custom headers.

Returns: error?

Sample code:

check hubspotClient->/["123456"].delete();

Restore a deleted list

Signature: put /[string listId]/restore

Restores a previously deleted list.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the list to restore.
headers	map<string|string[]>	No	Custom headers.

Returns: error?

Sample code:

check hubspotClient->/["123456"]/restore.put();

Membership management

Add records to a list

Signature: put /[string listId]/memberships/add

Adds records to a MANUAL or SNAPSHOT list by record IDs.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the MANUAL or SNAPSHOT list.
payload	string[]	Yes	Array of record IDs to add.
headers	map<string|string[]>	No	Custom headers.

Returns: MembershipsUpdateResponse|error

Sample code:

hslists:MembershipsUpdateResponse response = check hubspotClient->/["123456"]/memberships/add.put(["85187972687", "85187972688", "85187972689"]);

Sample response:

{
  "recordsIdsAdded": ["85187972687", "85187972688", "85187972689"],
  "recordIdsMissing": []
}

Remove records from a list

Signature: put /[string listId]/memberships/remove

Removes records from a MANUAL or SNAPSHOT list by record IDs.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the MANUAL or SNAPSHOT list.
payload	string[]	Yes	Array of record IDs to remove.
headers	map<string|string[]>	No	Custom headers.

Returns: MembershipsUpdateResponse|error

Sample code:

hslists:MembershipsUpdateResponse response = check hubspotClient->/["123456"]/memberships/remove.put(["85187972687"]);

Sample response:

{
  "recordIdsRemoved": ["85187972687"],
  "recordIdsMissing": []
}

Add and remove records from a list

Signature: put /[string listId]/memberships/add-and-remove

Adds and/or removes records from a MANUAL or SNAPSHOT list in a single request.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the MANUAL or SNAPSHOT list.
payload	MembershipChangeRequest	Yes	Object with recordIdsToAdd and recordIdsToRemove arrays.
headers	map<string|string[]>	No	Custom headers.

Returns: MembershipsUpdateResponse|error

Sample code:

hslists:MembershipsUpdateResponse response = check hubspotClient->/["123456"]/memberships/"add-and-remove".put({
    recordIdsToAdd: ["85187972690", "85187972691"],
    recordIdsToRemove: ["85187972687"]
});

Sample response:

{
  "recordsIdsAdded": ["85187972690", "85187972691"],
  "recordIdsRemoved": ["85187972687"],
  "recordIdsMissing": []
}

Add all records from another list

Signature: put /[string listId]/memberships/add-from/[string sourceListId]

Adds all records from a source list to a destination MANUAL or SNAPSHOT list.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the destination list.
sourceListId	string	Yes	The ILS ID of the source list.
headers	map<string|string[]>	No	Custom headers.

Returns: error?

Sample code:

check hubspotClient->/["123456"]/memberships/"add-from"/["789012"].put();

Remove all records from a list

Signature: delete /[string listId]/memberships

Removes all records from a MANUAL or SNAPSHOT list.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the MANUAL or SNAPSHOT list.
headers	map<string|string[]>	No	Custom headers.

Returns: error?

Sample code:

check hubspotClient->/["123456"]/memberships.delete();

Fetch list memberships

Signature: get /[string listId]/memberships

Fetches list memberships ordered by record ID, with cursor-based pagination.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the list.
queries	GetListIdMembershipsGetPageQueries	No	Query parameters. limit (default 100), before, after for cursor pagination.
headers	map<string|string[]>	No	Custom headers.

Returns: ApiCollectionResponseJoinTimeAndRecordId|error

Sample code:

hslists:ApiCollectionResponseJoinTimeAndRecordId response = check hubspotClient->/["123456"]/memberships.get(queries = {'limit: 50});

Sample response:

{
  "total": 3,
  "results": [
    {"recordId": "85187972687", "addedAt": "2025-01-15T10:30:00.000Z"},
    {"recordId": "85187972688", "addedAt": "2025-01-15T10:31:00.000Z"},
    {"recordId": "85187972689", "addedAt": "2025-01-15T10:32:00.000Z"}
  ]
}

Fetch list memberships ordered by added date

Signature: get /[string listId]/memberships/join-order

Fetches list memberships ordered by the date each record was added to the list.

Parameters:

Name	Type	Required	Description
listId	string	Yes	The ILS ID of the list.
queries	GetListIdMembershipsJoinOrderGetPageOrderedByAddedToListDateQueries	No	Query parameters. limit (default 100), before, after for cursor pagination.
headers	map<string|string[]>	No	Custom headers.

Returns: ApiCollectionResponseJoinTimeAndRecordId|error

Sample code:

hslists:ApiCollectionResponseJoinTimeAndRecordId response = check hubspotClient->/["789012"]/memberships/"join-order".get();

Sample response:

{
  "total": 2,
  "results": [
    {"recordId": "85187972687", "addedAt": "2025-01-15T10:30:00.000Z"},
    {"recordId": "85187972688", "addedAt": "2025-01-16T14:20:00.000Z"}
  ]
}

Get lists for a record

Signature: get /records/[string objectTypeId]/[string recordId]/memberships

Gets all lists that a specific record is a member of.

Parameters:

Name	Type	Required	Description
objectTypeId	string	Yes	Object type ID of the record (e.g., "0-1" for contacts).
recordId	string	Yes	The ID of the record.
headers	map<string|string[]>	No	Custom headers.

Returns: ApiCollectionResponseRecordListMembershipNoPaging|error

Sample code:

hslists:ApiCollectionResponseRecordListMembershipNoPaging response = check hubspotClient->/records/["0-1"]/["85187972687"]/memberships.get();

Sample response:

{
  "total": 2,
  "results": [
    {"listId": "123456", "recordId": "85187972687", "listVersion": 1},
    {"listId": "123457", "recordId": "85187972687", "listVersion": 3}
  ]
}

Folder operations

Create a folder

Signature: post /folders

Creates a new folder to organize lists.

Parameters:

Name	Type	Required	Description
payload	ListFolderCreateRequest	Yes	Folder creation payload with name and optional parentFolderId.
headers	map<string|string[]>	No	Custom headers.

Returns: ListFolderCreateResponse|error

Sample code:

hslists:ListFolderCreateResponse response = check hubspotClient->/folders.post({
    name: "Customer Support Tickets"
});

Sample response:

{
  "folder": {
    "id": 456,
    "name": "Customer Support Tickets",
    "parentFolderId": 0
  }
}

Retrieve folder contents

Signature: get /folders

Retrieves a folder and its contents by folder ID.

Parameters:

Name	Type	Required	Description
queries	GetFoldersGetAllQueries	No	Query parameters. folderId (default "0": root folder).
headers	map<string|string[]>	No	Custom headers.

Returns: ListFolderFetchResponse|error

Sample code:

hslists:ListFolderFetchResponse response = check hubspotClient->/folders.get(queries = {folderId: "456"});

Sample response:

{
  "folder": {
    "id": 456,
    "name": "Customer Support Tickets",
    "parentFolderId": 0
  }
}

Rename a folder

Signature: put /folders/[string folderId]/rename

Renames an existing folder.

Parameters:

Name	Type	Required	Description
folderId	string	Yes	The ID of the folder to rename.
queries	PutFoldersFolderIdRenameRenameQueries	No	Query parameters. newFolderName: the new name.
headers	map<string|string[]>	No	Custom headers.

Returns: ListFolderFetchResponse|error

Sample code:

hslists:ListFolderFetchResponse response = check hubspotClient->/folders/["456"]/rename.put(queries = {newFolderName: "Support Tickets Archive"});

Sample response:

{
  "folder": {
    "id": 456,
    "name": "Support Tickets Archive",
    "parentFolderId": 0
  }
}

Move a folder

Signature: put /folders/[string folderId]/move/[string newParentFolderId]

Moves a folder to a new parent folder.

Parameters:

Name	Type	Required	Description
folderId	string	Yes	The ID of the folder to move.
newParentFolderId	string	Yes	The ID of the new parent folder.
headers	map<string|string[]>	No	Custom headers.

Returns: ListFolderFetchResponse|error

Sample code:

hslists:ListFolderFetchResponse response = check hubspotClient->/folders/["456"]/move/["789"].put();

Sample response:

{
  "folder": {
    "id": 456,
    "name": "Customer Support Tickets",
    "parentFolderId": 789
  }
}

Move a list to a folder

Signature: put /folders/move-list

Moves a list to a specified folder.

Parameters:

Name	Type	Required	Description
payload	ListMoveRequest	Yes	Object with listId and newFolderId.
headers	map<string|string[]>	No	Custom headers.

Returns: error?

Sample code:

check hubspotClient->/folders/"move-list".put({
    listId: "123456",
    newFolderId: "456"
});

Delete a folder

Signature: delete /folders/[string folderId]

Deletes a folder by its ID.

Parameters:

Name	Type	Required	Description
folderId	string	Yes	The ID of the folder to delete.
headers	map<string|string[]>	No	Custom headers.

Returns: error?

Sample code:

check hubspotClient->/folders/["456"].delete();

Legacy ID mapping

Translate a legacy list ID

Signature: get /idmapping

Translates a single legacy list ID to the modern ILS list ID.

Parameters:

Name	Type	Required	Description
queries	GetIdmappingTranslateLegacyListIdToListIdQueries	No	Query parameters. legacyListId: the legacy list ID to translate.
headers	map<string|string[]>	No	Custom headers.

Returns: PublicMigrationMapping|error

Sample code:

hslists:PublicMigrationMapping response = check hubspotClient->/idmapping.get(queries = {legacyListId: "100"});

Sample response:

{
  "listId": "123456",
  "legacyListId": "100"
}

Translate legacy list IDs in batch

Signature: post /idmapping

Translates multiple legacy list IDs to modern ILS list IDs in a single batch request.

Parameters:

Name	Type	Required	Description
payload	string[]	Yes	Array of legacy list IDs to translate.
headers	map<string|string[]>	No	Custom headers.

Returns: PublicBatchMigrationMapping|error

Sample code:

hslists:PublicBatchMigrationMapping response = check hubspotClient->/idmapping.post(["100", "200", "300"]);

Sample response:

{
  "legacyListIdsToIdsMapping": [
    {"listId": "123456", "legacyListId": "100"},
    {"listId": "789012", "legacyListId": "200"}
  ],
  "missingLegacyListIds": ["300"]
}