Actions

The ballerinax/hubspot.marketing.forms package exposes the following clients:

Client	Purpose
`Client`	Manage HubSpot marketing forms: create, list, retrieve, update, and archive form definitions.

Client

Manage HubSpot marketing forms: create, list, retrieve, update, and archive form definitions.

Configuration

Field	Type	Default	Description
`auth`	`OAuth2RefreshTokenGrantConfig\|http:BearerTokenConfig\|ApiKeysConfig`	Required	Authentication configuration: OAuth 2.0 refresh token, bearer token, or private app API key.
`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 for HTTP requests.
`validation`	`boolean`	`true`	Enable or disable payload validation.

Initializing the client

import ballerina/oauth2;
import ballerinax/hubspot.marketing.forms as forms;

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

forms:Client formsClient = check new ({
    auth: {
        clientId: clientId,
        clientSecret: clientSecret,
        refreshToken: refreshToken,
        credentialBearer: oauth2:POST_BODY_BEARER
    }
});

Operations

Form creation

Create a form

Signature: post /

Creates a new marketing form with the specified field groups, configuration, display options, and legal consent settings.

Parameters:

Name	Type	Required	Description
`payload`	`FormDefinitionCreateRequestBase`	Yes	The form definition to create, including name, field groups, configuration, display options, and legal consent options.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: FormDefinitionBase|error

Sample code:

forms:FormDefinitionBase response = check formsClient->/.post({
    name: "Contact Us Form",
    formType: "hubspot",
    fieldGroups: [
        {
            groupType: "default_group",
            richTextType: "text",
            fields: [
                {
                    name: "email",
                    label: "Email",
                    fieldType: "email",
                    objectTypeId: "0-1",
                    required: true,
                    hidden: false,
                    validation: {
                        useDefaultBlockList: true,
                        blockedEmailDomains: []
                    }
                }
            ]
        }
    ],
    configuration: {
        language: "en",
        createNewContactForNewEmail: true,
        editable: true,
        allowLinkToResetKnownValues: false,
        postSubmitAction: {
            'type: "thank_you",
            value: "Thank you for contacting us!"
        },
        prePopulateKnownValues: true,
        cloneable: true,
        notifyContactOwner: false,
        recaptchaEnabled: false,
        archivable: true,
        notifyRecipients: []
    },
    displayOptions: {
        renderRawHtml: false,
        theme: "default_style",
        submitButtonText: "Submit",
        style: {
            labelTextSize: "13",
            legalConsentTextColor: "#33475b",
            fontFamily: "arial, helvetica, sans-serif",
            legalConsentTextSize: "14",
            backgroundWidth: "100%",
            helpTextSize: "11",
            submitFontColor: "#ffffff",
            labelTextColor: "#33475b",
            submitAlignment: "left",
            submitSize: "12",
            helpTextColor: "#7c98b6",
            submitColor: "#ff7a59"
        }
    },
    legalConsentOptions: {
        'type: "none"
    }
});

Sample response:

{
  "id": "12345678-abcd-1234-efgh-123456789012",
  "name": "Contact Us Form",
  "formType": "hubspot",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false,
  "fieldGroups": [
    {
      "groupType": "default_group",
      "richTextType": "text",
      "fields": [
        {
          "name": "email",
          "label": "Email",
          "fieldType": "email",
          "objectTypeId": "0-1",
          "required": true,
          "hidden": false,
          "validation": {
            "useDefaultBlockList": true,
            "blockedEmailDomains": []
          }
        }
      ]
    }
  ],
  "configuration": {
    "language": "en",
    "createNewContactForNewEmail": true,
    "editable": true,
    "allowLinkToResetKnownValues": false,
    "postSubmitAction": {
      "type": "thank_you",
      "value": "Thank you for contacting us!"
    },
    "prePopulateKnownValues": true,
    "cloneable": true,
    "notifyContactOwner": false,
    "recaptchaEnabled": false,
    "archivable": true,
    "notifyRecipients": []
  },
  "displayOptions": {
    "renderRawHtml": false,
    "theme": "default_style",
    "submitButtonText": "Submit",
    "style": {
      "labelTextSize": "13",
      "legalConsentTextColor": "#33475b",
      "fontFamily": "arial, helvetica, sans-serif",
      "legalConsentTextSize": "14",
      "backgroundWidth": "100%",
      "helpTextSize": "11",
      "submitFontColor": "#ffffff",
      "labelTextColor": "#33475b",
      "submitAlignment": "left",
      "submitSize": "12",
      "helpTextColor": "#7c98b6",
      "submitColor": "#ff7a59"
    }
  },
  "legalConsentOptions": {
    "type": "none"
  }
}

Form retrieval

Get a form definition by ID

Signature: get /[string formId]

Retrieves a single form definition by its unique identifier. Optionally includes archived forms.

Parameters:

Name	Type	Required	Description
`formId`	`string`	Yes	The unique identifier of the form.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`GetMarketingV3FormsFormIdGetByIdQueries`	No	Query parameters: `archived` (boolean) to include archived forms.

Returns: FormDefinitionBase|error

Sample code:

forms:FormDefinitionBase form = check formsClient->/[formId]();

Sample response:

{
  "id": "12345678-abcd-1234-efgh-123456789012",
  "name": "Contact Us Form",
  "formType": "hubspot",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false,
  "fieldGroups": [
    {
      "groupType": "default_group",
      "richTextType": "text",
      "fields": [
        {
          "name": "email",
          "label": "Email",
          "fieldType": "email",
          "objectTypeId": "0-1",
          "required": true,
          "hidden": false,
          "validation": {
            "useDefaultBlockList": true,
            "blockedEmailDomains": []
          }
        }
      ]
    }
  ],
  "configuration": {
    "language": "en",
    "createNewContactForNewEmail": true,
    "editable": true,
    "allowLinkToResetKnownValues": false,
    "postSubmitAction": {
      "type": "thank_you",
      "value": "Thank you for contacting us!"
    },
    "prePopulateKnownValues": true,
    "cloneable": true,
    "notifyContactOwner": false,
    "recaptchaEnabled": false,
    "archivable": true,
    "notifyRecipients": []
  },
  "displayOptions": {
    "renderRawHtml": false,
    "theme": "default_style",
    "submitButtonText": "Submit",
    "style": {
      "labelTextSize": "13",
      "legalConsentTextColor": "#33475b",
      "fontFamily": "arial, helvetica, sans-serif",
      "legalConsentTextSize": "14",
      "backgroundWidth": "100%",
      "helpTextSize": "11",
      "submitFontColor": "#ffffff",
      "labelTextColor": "#33475b",
      "submitAlignment": "left",
      "submitSize": "12",
      "helpTextColor": "#7c98b6",
      "submitColor": "#ff7a59"
    }
  },
  "legalConsentOptions": {
    "type": "none"
  }
}

List forms

Signature: get /

Returns a paginated list of form definitions. Supports filtering by form type and archive status.

Parameters:

Name	Type	Required	Description
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`GetMarketingV3FormsGetPageQueries`	No	Query parameters: `formTypes` (array of `hubspot`, `captured`, `flow`, `blog_comment`, `all`), `archived` (boolean), `limit` (int), `after` (string cursor).

Returns: CollectionResponseFormDefinitionBaseForwardPaging|error

Sample code:

forms:CollectionResponseFormDefinitionBaseForwardPaging response = check formsClient->/.get();

Sample response:

{
  "results": [
    {
      "id": "12345678-abcd-1234-efgh-123456789012",
      "name": "Contact Us Form",
      "formType": "hubspot",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false,
      "fieldGroups": [],
      "configuration": {},
      "displayOptions": {},
      "legalConsentOptions": {"type": "none"}
    }
  ],
  "paging": {
    "next": {
      "after": "NTI1Cg%3D%3D",
      "link": "https://api.hubapi.com/marketing/v3/forms?after=NTI1Cg%3D%3D"
    }
  }
}

Form updates

Replace a form definition

Signature: put /[string formId]

Performs a full replacement of a form definition. All fields in the payload will overwrite the existing form.

Parameters:

Name	Type	Required	Description
`formId`	`string`	Yes	The unique identifier of the form to replace.
`payload`	`HubSpotFormDefinition`	Yes	The complete form definition to replace the existing one.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: FormDefinitionBase|error

Sample code:

forms:FormDefinitionBase response = check formsClient->/[formId].put({
    name: "Updated Contact Us Form",
    formType: "hubspot",
    createdAt: "2025-01-15T10:30:00.000Z",
    updatedAt: "2025-01-16T08:00:00.000Z",
    id: formId,
    archived: false,
    fieldGroups: [
        {
            groupType: "default_group",
            richTextType: "text",
            fields: [
                {
                    name: "email",
                    label: "Email Address",
                    fieldType: "email",
                    objectTypeId: "0-1",
                    required: true,
                    hidden: false,
                    validation: {
                        useDefaultBlockList: true,
                        blockedEmailDomains: []
                    }
                }
            ]
        }
    ],
    configuration: {
        language: "en",
        createNewContactForNewEmail: true,
        editable: true,
        allowLinkToResetKnownValues: false,
        postSubmitAction: {
            'type: "thank_you",
            value: "Thanks for reaching out!"
        },
        prePopulateKnownValues: true,
        cloneable: true,
        notifyContactOwner: false,
        recaptchaEnabled: false,
        archivable: true,
        notifyRecipients: []
    },
    displayOptions: {
        renderRawHtml: false,
        theme: "default_style",
        submitButtonText: "Send",
        style: {
            labelTextSize: "13",
            legalConsentTextColor: "#33475b",
            fontFamily: "arial, helvetica, sans-serif",
            legalConsentTextSize: "14",
            backgroundWidth: "100%",
            helpTextSize: "11",
            submitFontColor: "#ffffff",
            labelTextColor: "#33475b",
            submitAlignment: "left",
            submitSize: "12",
            helpTextColor: "#7c98b6",
            submitColor: "#ff7a59"
        }
    },
    legalConsentOptions: {
        'type: "none"
    }
});

Sample response:

{
  "id": "12345678-abcd-1234-efgh-123456789012",
  "name": "Updated Contact Us Form",
  "formType": "hubspot",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T08:00:00.000Z",
  "archived": false,
  "fieldGroups": [
    {
      "groupType": "default_group",
      "richTextType": "text",
      "fields": [
        {
          "name": "email",
          "label": "Email Address",
          "fieldType": "email",
          "objectTypeId": "0-1",
          "required": true,
          "hidden": false,
          "validation": {
            "useDefaultBlockList": true,
            "blockedEmailDomains": []
          }
        }
      ]
    }
  ],
  "configuration": {
    "language": "en",
    "createNewContactForNewEmail": true,
    "editable": true,
    "allowLinkToResetKnownValues": false,
    "postSubmitAction": {
      "type": "thank_you",
      "value": "Thanks for reaching out!"
    },
    "prePopulateKnownValues": true,
    "cloneable": true,
    "notifyContactOwner": false,
    "recaptchaEnabled": false,
    "archivable": true,
    "notifyRecipients": []
  },
  "displayOptions": {
    "renderRawHtml": false,
    "theme": "default_style",
    "submitButtonText": "Send",
    "style": {
      "labelTextSize": "13",
      "legalConsentTextColor": "#33475b",
      "fontFamily": "arial, helvetica, sans-serif",
      "legalConsentTextSize": "14",
      "backgroundWidth": "100%",
      "helpTextSize": "11",
      "submitFontColor": "#ffffff",
      "labelTextColor": "#33475b",
      "submitAlignment": "left",
      "submitSize": "12",
      "helpTextColor": "#7c98b6",
      "submitColor": "#ff7a59"
    }
  },
  "legalConsentOptions": {
    "type": "none"
  }
}

Partially update a form definition

Signature: patch /[string formId]

Partially updates a form definition. Only the fields included in the payload are modified; all other fields remain unchanged.

Parameters:

Name	Type	Required	Description
`formId`	`string`	Yes	The unique identifier of the form to update.
`payload`	`HubSpotFormDefinitionPatchRequest`	Yes	The fields to update: `name`, `fieldGroups`, `configuration`, `displayOptions`, `legalConsentOptions`, `archived`.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: FormDefinitionBase|error

Sample code:

forms:FormDefinitionBase response = check formsClient->/[formId].patch({
    fieldGroups: [
        {
            groupType: "default_group",
            richTextType: "text",
            fields: [
                {
                    name: "email",
                    label: "Email",
                    fieldType: "email",
                    objectTypeId: "0-1",
                    required: true,
                    hidden: false,
                    validation: {
                        useDefaultBlockList: true,
                        blockedEmailDomains: []
                    }
                }
            ]
        },
        {
            groupType: "default_group",
            richTextType: "text",
            fields: [
                {
                    name: "firstname",
                    label: "First Name",
                    fieldType: "single_line_text",
                    objectTypeId: "0-1",
                    required: true,
                    hidden: false
                },
                {
                    name: "lastname",
                    label: "Last Name",
                    fieldType: "single_line_text",
                    objectTypeId: "0-1",
                    required: true,
                    hidden: false
                }
            ]
        },
        {
            groupType: "default_group",
            richTextType: "text",
            fields: [
                {
                    name: "phone",
                    label: "Phone Number",
                    fieldType: "phone",
                    objectTypeId: "0-1",
                    required: false,
                    hidden: false,
                    useCountryCodeSelect: true,
                    validation: {
                        minAllowedDigits: 10,
                        maxAllowedDigits: 10
                    }
                }
            ]
        },
        {
            groupType: "default_group",
            richTextType: "text",
            fields: [
                {
                    name: "message",
                    label: "Message",
                    fieldType: "multi_line_text",
                    objectTypeId: "0-1",
                    required: false,
                    hidden: false
                }
            ]
        }
    ]
});

Sample response:

{
  "id": "12345678-abcd-1234-efgh-123456789012",
  "name": "Contact Us Form",
  "formType": "hubspot",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T09:15:00.000Z",
  "archived": false,
  "fieldGroups": [
    {
      "groupType": "default_group",
      "richTextType": "text",
      "fields": [
        {"name": "email", "label": "Email", "fieldType": "email", "objectTypeId": "0-1", "required": true, "hidden": false}
      ]
    },
    {
      "groupType": "default_group",
      "richTextType": "text",
      "fields": [
        {"name": "firstname", "label": "First Name", "fieldType": "single_line_text", "objectTypeId": "0-1", "required": true, "hidden": false},
        {"name": "lastname", "label": "Last Name", "fieldType": "single_line_text", "objectTypeId": "0-1", "required": true, "hidden": false}
      ]
    },
    {
      "groupType": "default_group",
      "richTextType": "text",
      "fields": [
        {"name": "phone", "label": "Phone Number", "fieldType": "phone", "objectTypeId": "0-1", "required": false, "hidden": false}
      ]
    },
    {
      "groupType": "default_group",
      "richTextType": "text",
      "fields": [
        {"name": "message", "label": "Message", "fieldType": "multi_line_text", "objectTypeId": "0-1", "required": false, "hidden": false}
      ]
    }
  ],
  "configuration": {},
  "displayOptions": {},
  "legalConsentOptions": {"type": "none"}
}

Form archival

Archive a form definition

Signature: delete /[string formId]

Archives (soft-deletes) a form definition. Archived forms can still be retrieved by setting the archived query parameter to true.

Parameters:

Name	Type	Required	Description
`formId`	`string`	Yes	The unique identifier of the form to archive.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: json|error

Sample code:

json response = check formsClient->/[formId].delete();

Client​

Configuration​

Initializing the client​

Operations​

Form creation​

Form retrieval​

Form updates​

Form archival​

Client

Configuration

Initializing the client

Operations

Form creation

Form retrieval

Form updates

Form archival