Actions

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

Client	Purpose
Client	Manage association definitions and configurations between HubSpot CRM object types.

---

Client

Manage association definitions and configurations between HubSpot CRM object types.

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig	Required	OAuth 2.0 refresh token config, bearer token, or 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.
compression	http:Compression	COMPRESSION_AUTO	Compression configuration.
circuitBreaker	http:CircuitBreakerConfig	()	Circuit breaker configuration.
cache	http:CacheConfig	{}	HTTP cache configuration.
validation	boolean	true	Enable/disable payload validation.
laxDataBinding	boolean	true	Enable/disable lax data binding.

Initializing the client

import ballerina/oauth2;
import ballerinax/hubspot.crm.associations.schema as hsschema;

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

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

final hsschema:Client hubspot = check new ({auth});

Operations

Association definitions (labels)

Read association definitions between two object types

Signature: get [string fromObjectType]/[string toObjectType]/labels

Retrieves all association definitions (labels) between two specified CRM object types.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type (e.g., "contacts", "companies").
toObjectType	string	Yes	The target object type (e.g., "deals", "companies").
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: CollectionResponseAssociationSpecWithLabelNoPaging|error

Sample code:

hsschema:CollectionResponseAssociationSpecWithLabelNoPaging associations =
    check hubspot->/["contacts"]/["deals"]/labels;

Sample response:

{
  "results": [
    {
      "typeId": 3,
      "label": null,
      "category": "HUBSPOT_DEFINED"
    },
    {
      "typeId": 4,
      "label": null,
      "category": "HUBSPOT_DEFINED"
    }
  ]
}

Create a user-defined association definition

Signature: post [string fromObjectType]/[string toObjectType]/labels

Creates a new user-defined association definition with a label and optional inverse label between two CRM object types.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type.
toObjectType	string	Yes	The target object type.
payload	PublicAssociationDefinitionCreateRequest	Yes	The association definition to create, including name, optional label, and optional inverseLabel.
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: CollectionResponseAssociationSpecWithLabelNoPaging|error

Sample code:

hsschema:PublicAssociationDefinitionCreateRequest payload = {
    name: "Headquarters_Franchise",
    label: "Franchise company",
    inverseLabel: "Headquarters company"
};

hsschema:CollectionResponseAssociationSpecWithLabelNoPaging result =
    check hubspot->/["companies"]/["companies"]/labels.post(payload);

Sample response:

{
  "results": [
    {
      "typeId": 35,
      "label": "Franchise company",
      "category": "USER_DEFINED"
    },
    {
      "typeId": 36,
      "label": "Headquarters company",
      "category": "USER_DEFINED"
    }
  ]
}

Update a user-defined association definition

Signature: put [string fromObjectType]/[string toObjectType]/labels

Updates the label and inverse label of an existing user-defined association definition.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type.
toObjectType	string	Yes	The target object type.
payload	PublicAssociationDefinitionUpdateRequest	Yes	The update payload including associationTypeId, label, and optional inverseLabel.
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: error?

Sample code:

hsschema:PublicAssociationDefinitionUpdateRequest payload = {
    associationTypeId: 35,
    label: "Franchise company updated",
    inverseLabel: "Headquarters company updated"
};

check hubspot->/["companies"]/["companies"]/labels.put(payload);

Delete an association definition

Signature: delete [string fromObjectType]/[string toObjectType]/labels/[int:Signed32 associationTypeId]

Deletes a user-defined association definition by its type ID.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type.
toObjectType	string	Yes	The target object type.
associationTypeId	int:Signed32	Yes	The ID of the association type to delete.
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: error?

Sample code:

check hubspot->/["companies"]/["companies"]/labels/[35].delete();

Association configurations

Retrieve all association configurations

Signature: get definitions/configurations/all

Retrieves all association definition configurations across all object types.

Parameters:

Name	Type	Required	Description
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: CollectionResponsePublicAssociationDefinitionUserConfigurationNoPaging|error

Sample code:

hsschema:CollectionResponsePublicAssociationDefinitionUserConfigurationNoPaging configs =
    check hubspot->/definitions/configurations/all;

Sample response:

{
  "results": [
    {
      "typeId": 3,
      "category": "HUBSPOT_DEFINED",
      "label": null,
      "userEnforcedMaxToObjectIds": 1
    },
    {
      "typeId": 449,
      "category": "HUBSPOT_DEFINED",
      "label": null,
      "userEnforcedMaxToObjectIds": 5
    }
  ]
}

Retrieve configurations between two object types

Signature: get definitions/configurations/[string fromObjectType]/[string toObjectType]

Retrieves association configurations between two specified CRM object types.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type.
toObjectType	string	Yes	The target object type.
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: CollectionResponsePublicAssociationDefinitionUserConfigurationNoPaging|error

Sample code:

hsschema:CollectionResponsePublicAssociationDefinitionUserConfigurationNoPaging configs =
    check hubspot->/definitions/configurations/["contacts"]/["contacts"];

Sample response:

{
  "results": [
    {
      "typeId": 449,
      "category": "HUBSPOT_DEFINED",
      "label": null,
      "userEnforcedMaxToObjectIds": 2
    }
  ]
}

Batch create association configurations

Signature: post definitions/configurations/[string fromObjectType]/[string toObjectType]/batch/create

Creates multiple association configurations in a single batch request, setting cardinality constraints.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type.
toObjectType	string	Yes	The target object type.
payload	BatchInputPublicAssociationDefinitionConfigurationCreateRequest	Yes	Batch of configuration create requests, each with typeId, category, and maxToObjectIds.
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: BatchResponsePublicAssociationDefinitionUserConfiguration|BatchResponsePublicAssociationDefinitionUserConfigurationWithErrors|error

Sample code:

hsschema:BatchInputPublicAssociationDefinitionConfigurationCreateRequest payload = {
    inputs: [
        {
            typeId: 449,
            category: "HUBSPOT_DEFINED",
            maxToObjectIds: 5
        }
    ]
};

hsschema:BatchResponsePublicAssociationDefinitionUserConfiguration|
    hsschema:BatchResponsePublicAssociationDefinitionUserConfigurationWithErrors result =
    check hubspot->/definitions/configurations/["contacts"]/["contacts"]/batch/create(payload);

Sample response:

{
  "completedAt": "2025-01-15T10:30:00.000Z",
  "startedAt": "2025-01-15T10:29:59.000Z",
  "results": [
    {
      "typeId": 449,
      "category": "HUBSPOT_DEFINED",
      "userEnforcedMaxToObjectIds": 5
    }
  ],
  "status": "COMPLETE"
}

Batch update association configurations

Signature: post definitions/configurations/[string fromObjectType]/[string toObjectType]/batch/update

Updates multiple association configurations in a single batch request.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type.
toObjectType	string	Yes	The target object type.
payload	BatchInputPublicAssociationDefinitionConfigurationUpdateRequest	Yes	Batch of configuration update requests, each with typeId, category, and maxToObjectIds.
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: BatchResponsePublicAssociationDefinitionConfigurationUpdateResult|BatchResponsePublicAssociationDefinitionConfigurationUpdateResultWithErrors|error

Sample code:

hsschema:BatchInputPublicAssociationDefinitionConfigurationUpdateRequest payload = {
    inputs: [
        {
            typeId: 449,
            category: "HUBSPOT_DEFINED",
            maxToObjectIds: 10
        }
    ]
};

hsschema:BatchResponsePublicAssociationDefinitionConfigurationUpdateResult|
    hsschema:BatchResponsePublicAssociationDefinitionConfigurationUpdateResultWithErrors result =
    check hubspot->/definitions/configurations/["contacts"]/["contacts"]/batch/update(payload);

Sample response:

{
  "completedAt": "2025-01-15T11:00:00.000Z",
  "startedAt": "2025-01-15T10:59:59.000Z",
  "results": [
    {
      "typeId": 449,
      "category": "HUBSPOT_DEFINED",
      "userEnforcedMaxToObjectIds": 10
    }
  ],
  "status": "COMPLETE"
}

Batch delete association configurations

Signature: post definitions/configurations/[string fromObjectType]/[string toObjectType]/batch/purge

Deletes multiple association configurations in a single batch request.

Parameters:

Name	Type	Required	Description
fromObjectType	string	Yes	The source object type.
toObjectType	string	Yes	The target object type.
payload	BatchInputPublicAssociationSpec	Yes	Batch of association specs to delete, each with typeId and category.
headers	map<string|string[]>	No	Optional custom HTTP headers.

Returns: error?

Sample code:

hsschema:BatchInputPublicAssociationSpec payload = {
    inputs: [
        {
            typeId: 449,
            category: "HUBSPOT_DEFINED"
        }
    ]
};

check hubspot->/definitions/configurations/["contacts"]/["contacts"]/batch/purge(payload);