Actions

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

Client	Purpose
`Client`	Manage CRM object properties and property groups via the HubSpot Properties API.

Client

Manage CRM object properties and property groups via the HubSpot Properties API.

Configuration

Field	Type	Default	Description
`auth`	`http:BearerTokenConfig\|OAuth2RefreshTokenGrantConfig\|ApiKeysConfig`	Required	Authentication configuration: OAuth 2.0 refresh token grant, bearer token, or API keys.
`httpVersion`	`http:HttpVersion`	`http:HTTP_2_0`	HTTP protocol version.
`timeout`	`decimal`	`30`	The maximum time to wait (in seconds) for a response before closing the connection.
`retryConfig`	`http:RetryConfig`	`()`	Retry configuration for failed requests.
`secureSocket`	`http:ClientSecureSocket`	`()`	SSL/TLS configuration.
`proxy`	`http:ProxyConfig`	`()`	Proxy server configuration.
`compression`	`http:Compression`	`http:COMPRESSION_AUTO`	Specifies the way of handling compression (`accept-encoding`) header.
`circuitBreaker`	`http:CircuitBreakerConfig`	`()`	Circuit breaker configuration for fault tolerance.
`validation`	`boolean`	`true`	Enables inbound payload validation via the constraint package.

Initializing the client

import ballerina/oauth2;
import ballerinax/hubspot.crm.properties as hsproperties;

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

hsproperties:OAuth2RefreshTokenGrantConfig auth = {
    clientId: clientId,
    clientSecret: clientSecret,
    refreshToken: refreshToken,
    credentialBearer: oauth2:POST_BODY_BEARER
};
final hsproperties:Client hubSpotProperties = check new ({auth});

Operations

Property CRUD

Read all properties

Signature: get /[string objectType]

Read all existing properties for the specified object type. Returns a list of all properties, including default and custom properties.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`, `"Company"`, `"Deal"`).
`queries`	`GetCrmV3PropertiesObjectTypeGetAllQueries`	No	Query parameters: `archived` (default `false`) and `properties` (comma-separated field list).

Returns: CollectionResponsePropertyNoPaging|error

Sample code:

hsproperties:CollectionResponsePropertyNoPaging result = check hubSpotProperties->/Contact;

Sample response:

{
  "results": [
    {
      "name": "email",
      "label": "Email",
      "type": "string",
      "fieldType": "text",
      "description": "Contact's email address",
      "groupName": "contactinformation",
      "options": [],
      "archived": false
    }
  ]
}

Create a property

Signature: post /[string objectType]

Create a new property for the specified object type.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`payload`	`PropertyCreate`	Yes	Property definition including name, label, type, fieldType, groupName, and options.

Returns: Property|error

Sample code:

hsproperties:PropertyCreate newProperty = {
    name: "purchase_frequency",
    label: "Purchase Frequency",
    groupName: "customer_behavior",
    'type: "enumeration",
    fieldType: "select",
    description: "How often the customer makes purchases",
    options: [
        {label: "Daily", value: "daily", hidden: false, displayOrder: 1},
        {label: "Weekly", value: "weekly", hidden: false, displayOrder: 2},
        {label: "Monthly", value: "monthly", hidden: false, displayOrder: 3}
    ],
    hidden: false,
    formField: true,
    displayOrder: 1
};
hsproperties:Property result = check hubSpotProperties->/Contact.post(payload = newProperty);

Sample response:

{
  "name": "purchase_frequency",
  "label": "Purchase Frequency",
  "type": "enumeration",
  "fieldType": "select",
  "groupName": "customer_behavior",
  "description": "How often the customer makes purchases",
  "options": [
    {"label": "Daily", "value": "daily", "hidden": false, "displayOrder": 1},
    {"label": "Weekly", "value": "weekly", "hidden": false, "displayOrder": 2},
    {"label": "Monthly", "value": "monthly", "hidden": false, "displayOrder": 3}
  ],
  "hidden": false,
  "formField": true,
  "displayOrder": 1,
  "hasUniqueValue": false,
  "archived": false,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Read a property

Signature: get /[string objectType]/[string propertyName]

Read a property identified by its name for the specified object type.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`propertyName`	`string`	Yes	The internal name of the property to read.
`queries`	`GetCrmV3PropertiesObjectTypePropertyNameGetByNameQueries`	No	Query parameters: `archived` (default `false`) and `properties` (comma-separated field list).

Returns: Property|error

Sample code:

hsproperties:Property result = check hubSpotProperties->/Contact/purchase_frequency;

Sample response:

{
  "name": "purchase_frequency",
  "label": "Purchase Frequency",
  "type": "enumeration",
  "fieldType": "select",
  "groupName": "customer_behavior",
  "description": "How often the customer makes purchases",
  "options": [
    {"label": "Daily", "value": "daily", "hidden": false, "displayOrder": 1},
    {"label": "Weekly", "value": "weekly", "hidden": false, "displayOrder": 2},
    {"label": "Monthly", "value": "monthly", "hidden": false, "displayOrder": 3}
  ],
  "hidden": false,
  "formField": true,
  "displayOrder": 1,
  "hasUniqueValue": false,
  "archived": false
}

Update a property

Signature: patch /[string objectType]/[string propertyName]

Update an existing property identified by its name. Only the fields provided in the payload will be updated.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`propertyName`	`string`	Yes	The internal name of the property to update.
`payload`	`PropertyUpdate`	Yes	Fields to update: label, type, fieldType, groupName, description, options, etc.

Returns: Property|error

Sample code:

hsproperties:PropertyUpdate update = {
    options: [
        {label: "Daily", value: "daily", displayOrder: 1, hidden: false},
        {label: "Weekly", value: "weekly", displayOrder: 2, hidden: false},
        {label: "Monthly", value: "monthly", displayOrder: 3, hidden: false},
        {label: "Quarterly", value: "quarterly", displayOrder: 4, hidden: false}
    ]
};
hsproperties:Property result = check hubSpotProperties->/Contact/purchase_frequency.patch(payload = update);

Sample response:

{
  "name": "purchase_frequency",
  "label": "Purchase Frequency",
  "type": "enumeration",
  "fieldType": "select",
  "groupName": "customer_behavior",
  "options": [
    {"label": "Daily", "value": "daily", "hidden": false, "displayOrder": 1},
    {"label": "Weekly", "value": "weekly", "hidden": false, "displayOrder": 2},
    {"label": "Monthly", "value": "monthly", "hidden": false, "displayOrder": 3},
    {"label": "Quarterly", "value": "quarterly", "hidden": false, "displayOrder": 4}
  ],
  "hidden": false,
  "formField": true,
  "displayOrder": 1,
  "archived": false,
  "updatedAt": "2025-01-15T11:00:00.000Z"
}

Archive a property

Signature: delete /[string objectType]/[string propertyName]

Archive a property identified by its name. Archived properties are hidden from the HubSpot UI but can still be read with the archived query parameter.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`propertyName`	`string`	Yes	The internal name of the property to archive.

Returns: error?

Sample code:

check hubSpotProperties->/Contact/purchase_frequency.delete();

Batch operations

Create a batch of properties

Signature: post /[string objectType]/batch/create

Create multiple properties for the specified object type in a single request.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`payload`	`BatchInputPropertyCreate`	Yes	An object containing an `inputs` array of `PropertyCreate` records.

Returns: BatchResponseProperty|BatchResponsePropertyWithErrors|error

Sample code:

hsproperties:BatchInputPropertyCreate batchInput = {
    inputs: [
        {
            name: "email_subscription",
            label: "Email Subscription",
            groupName: "marketing_preference",
            'type: "enumeration",
            fieldType: "checkbox",
            description: "Track email subscription status",
            options: [
                {label: "Subscribed", value: "subscribed", hidden: false, displayOrder: 1},
                {label: "Unsubscribed", value: "unsubscribed", hidden: false, displayOrder: 2}
            ],
            hidden: false,
            formField: true,
            displayOrder: 1
        },
        {
            name: "sms_subscription",
            label: "SMS Subscription",
            groupName: "marketing_preference",
            'type: "enumeration",
            fieldType: "checkbox",
            description: "Track SMS subscription status",
            options: [
                {label: "Subscribed", value: "subscribed", hidden: false, displayOrder: 1},
                {label: "Unsubscribed", value: "unsubscribed", hidden: false, displayOrder: 2}
            ],
            hidden: false,
            formField: true,
            displayOrder: 2
        }
    ]
};
hsproperties:BatchResponseProperty result = check hubSpotProperties->/Contact/batch/create.post(payload = batchInput);

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "name": "email_subscription",
      "label": "Email Subscription",
      "type": "enumeration",
      "fieldType": "checkbox",
      "groupName": "marketing_preference",
      "options": [
        {"label": "Subscribed", "value": "subscribed", "hidden": false, "displayOrder": 1},
        {"label": "Unsubscribed", "value": "unsubscribed", "hidden": false, "displayOrder": 2}
      ],
      "archived": false
    },
    {
      "name": "sms_subscription",
      "label": "SMS Subscription",
      "type": "enumeration",
      "fieldType": "checkbox",
      "groupName": "marketing_preference",
      "options": [
        {"label": "Subscribed", "value": "subscribed", "hidden": false, "displayOrder": 1},
        {"label": "Unsubscribed", "value": "unsubscribed", "hidden": false, "displayOrder": 2}
      ],
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T10:30:00.000Z",
  "completedAt": "2025-01-15T10:30:01.000Z"
}

Read a batch of properties

Signature: post /[string objectType]/batch/read

Read multiple properties by name for the specified object type in a single request.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`payload`	`BatchReadInputPropertyName`	Yes	An object containing an `inputs` array of `PropertyName` records and an `archived` boolean.

Returns: BatchResponseProperty|BatchResponsePropertyWithErrors|error

Sample code:

hsproperties:BatchReadInputPropertyName batchReadInput = {
    inputs: [
        {name: "email_subscription"},
        {name: "sms_subscription"}
    ],
    archived: false
};
hsproperties:BatchResponseProperty result = check hubSpotProperties->/Contact/batch/read.post(payload = batchReadInput);

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "name": "email_subscription",
      "label": "Email Subscription",
      "type": "enumeration",
      "fieldType": "checkbox",
      "groupName": "marketing_preference",
      "options": [
        {"label": "Subscribed", "value": "subscribed", "hidden": false, "displayOrder": 1},
        {"label": "Unsubscribed", "value": "unsubscribed", "hidden": false, "displayOrder": 2}
      ],
      "archived": false
    },
    {
      "name": "sms_subscription",
      "label": "SMS Subscription",
      "type": "enumeration",
      "fieldType": "checkbox",
      "groupName": "marketing_preference",
      "options": [
        {"label": "Subscribed", "value": "subscribed", "hidden": false, "displayOrder": 1},
        {"label": "Unsubscribed", "value": "unsubscribed", "hidden": false, "displayOrder": 2}
      ],
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T10:31:00.000Z",
  "completedAt": "2025-01-15T10:31:01.000Z"
}

Archive a batch of properties

Signature: post /[string objectType]/batch/archive

Archive multiple properties by name for the specified object type in a single request.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`payload`	`BatchInputPropertyName`	Yes	An object containing an `inputs` array of `PropertyName` records to archive.

Returns: error?

Sample code:

hsproperties:BatchInputPropertyName batchArchiveInput = {
    inputs: [
        {name: "email_subscription"},
        {name: "sms_subscription"}
    ]
};
check hubSpotProperties->/Contact/batch/archive.post(payload = batchArchiveInput);

Property group management

Create a property group

Signature: post /[string objectType]/groups

Create a new property group for organizing related properties under the specified object type.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`payload`	`PropertyGroupCreate`	Yes	Property group definition including name, label, and optional displayOrder.

Returns: PropertyGroup|error

Sample code:

hsproperties:PropertyGroupCreate groupInput = {
    name: "marketing_preference",
    label: "Marketing Preferences",
    displayOrder: 1
};
hsproperties:PropertyGroup result = check hubSpotProperties->/Contact/groups.post(payload = groupInput);

Sample response:

{
  "name": "marketing_preference",
  "label": "Marketing Preferences",
  "displayOrder": 1,
  "archived": false
}

Read a property group

Signature: get /[string objectType]/groups/[string groupName]

Read a property group identified by its name for the specified object type.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`groupName`	`string`	Yes	The internal name of the property group to read.

Returns: PropertyGroup|error

Sample code:

hsproperties:PropertyGroup result = check hubSpotProperties->/Contact/groups/marketing_preference;

Sample response:

{
  "name": "marketing_preference",
  "label": "Marketing Preferences",
  "displayOrder": 1,
  "archived": false
}

Update a property group

Signature: patch /[string objectType]/groups/[string groupName]

Update an existing property group identified by its name. Only the fields provided in the payload will be updated.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`groupName`	`string`	Yes	The internal name of the property group to update.
`payload`	`PropertyGroupUpdate`	Yes	Fields to update: `label` and/or `displayOrder`.

Returns: PropertyGroup|error

Sample code:

hsproperties:PropertyGroupUpdate groupUpdate = {
    label: "Customer Marketing Preferences",
    displayOrder: 2
};
hsproperties:PropertyGroup result = check hubSpotProperties->/Contact/groups/marketing_preference.patch(payload = groupUpdate);

Sample response:

{
  "name": "marketing_preference",
  "label": "Customer Marketing Preferences",
  "displayOrder": 2,
  "archived": false
}

Archive a property group

Signature: delete /[string objectType]/groups/[string groupName]

Archive a property group identified by its name. Properties within the group are not deleted but become ungrouped.

Parameters:

Name	Type	Required	Description
`objectType`	`string`	Yes	The CRM object type (e.g., `"Contact"`).
`groupName`	`string`	Yes	The internal name of the property group to archive.

Returns: error?

Sample code:

check hubSpotProperties->/Contact/groups/marketing_preference.delete();

Client​

Configuration​

Initializing the client​

Operations​

Property CRUD​

Batch operations​

Property group management​

Client

Configuration

Initializing the client

Operations

Property CRUD

Batch operations

Property group management