ioLoop Docs

Appearance

$io.hubspot ​

Server API reference.

Functions ​

$io.hubspot.createCallForContact ​

Create a call engagement and associate it with a HubSpot contact.

Usage ​

js
$io.hubspot.createCallForContact(connectionName, contactId, body, status, timestamp, customRequestProperties)

Description ​

Creates a Call engagement with a contact.

  • hs_call_body: Call notes or summary
  • hs_call_status: Call status (default COMPLETED)

Optional timestamp sets the time of the engagement.

Usage Scenarios ​

  • Log outbound or inbound calls with a contact
  • Track call activity for sales, support, or follow-ups
  • Record call notes and status

Parameters ​

connectionName ​

Type: String

Required: Yes

HubSpot connection name.

contactId ​

Type: String

Required: Yes

HubSpot contact ID.

body ​

Type: String

Required: Yes

Call summary text.

status ​

Type: String

Required: No

Call status (default 'COMPLETED').

timestamp ​

Type: Number or String

Required: No

Optional timestamp of the call.

customRequestProperties ​

Type: Object

Required: No

Optional advanced request options.

Output ​

Type: Promise

Returns { status, data, err } — engagement info or error message.

$io.hubspot.createContact ​

Create a new contact in HubSpot CRM with custom properties.

Usage ​

js
$io.hubspot.createContact(connectionName, properties, customRequestProperties)

Description ​

This function creates a new contact in HubSpot CRM using the /crm/v3/objects/contacts endpoint.

You must pass an object of field values in properties, which maps to HubSpot contact fields.

For example:

js
{
  email: "[email protected]",
  firstname: "Jane",
  lastname: "Doe",
  phone: "+1-555-1234"
}

You can optionally pass customRequestProperties to include headers or other advanced request settings. This is passed through to $io.hubspot.execApiRequest.

Usage Scenarios ​

  • Add leads or users as HubSpot contacts
  • Automate contact creation from form submissions
  • Sync external users into HubSpot CRM

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

properties ​

Type: Object

Required: Yes

Key-value pairs of contact fields to set. Example:

customRequestProperties ​

Type: Object

Required: No

Optional. Advanced request options (e.g., headers, timeouts) passed to the underlying API client.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if contact was successfully created
  • data: HubSpot API response with new contact metadata
  • err: Error message if creation failed

$io.hubspot.createEmailForContact ​

Create an email engagement and associate it with a HubSpot contact.

Usage ​

js
$io.hubspot.createEmailForContact(connectionName, contactId, subject, body, timestamp, direction, customRequestProperties)

Description ​

Creates an Email engagement and links it to a contact.

  • hs_email_subject: Email subject line
  • hs_email_text: Email body content
  • hs_email_direction: Email direction. Valid values:
    • OUTGOING → EMAIL
    • INCOMING → INCOMING_EMAIL
    • FORWARDED → FORWARDED_EMAIL

Direction defaults to OUTGOING. Timestamp defaults to current time if not supplied.

Usage Scenarios ​

  • Log outbound or incoming emails with contacts
  • Track CRM-related emails for activity history
  • Record forwarded messages or system emails

Parameters ​

connectionName ​

Type: String

Required: Yes

HubSpot connection name.

contactId ​

Type: String

Required: Yes

HubSpot contact ID.

subject ​

Type: String

Required: Yes

Email subject.

body ​

Type: String

Required: Yes

Email body content.

timestamp ​

Type: Number or String

Required: No

Optional timestamp (UNIX ms or ISO).

direction ​

Type: String

Required: No

Email direction: OUTGOING, INCOMING, FORWARDED (default: OUTGOING).

customRequestProperties ​

Type: Object

Required: No

Optional advanced request options.

Output ​

Type: Promise

Returns { status, data, err } — engagement info or error message.

$io.hubspot.createEngagementForContact ​

Create and associate an engagement (note, call, task, or email) with a HubSpot contact.

Usage ​

js
$io.hubspot.createEngagementForContact(connectionName, type, contactId, properties, timestamp, customRequestProperties)

Description ​

Creates a HubSpot engagement object (e.g., note, call, task, or email) and associates it with a specified contact.

This method supports the following type values:

  • note
  • call
  • task
  • email

It performs the following steps:

  1. Validates the type and determines the correct object and association endpoints
  2. Wraps the provided properties in a { properties: ... } payload
  3. Automatically assigns hs_timestamp if not present, using the provided timestamp or the current time
  4. Sends a POST request to create the engagement
  5. Sends a PUT request to associate the engagement to the given contactId

⚠️ Note: For most use cases, use helper methods like createNoteForContact or createCallForContact. Use this only when dynamically creating multiple types of engagements.

Usage Scenarios ​

  • Dynamically create CRM engagements by type
  • Power custom workflows or advanced integrations
  • Support generic engagement creation logic in internal tools

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in your ioLoop app.

type ​

Type: String

Required: Yes

Type of engagement: 'note', 'call', 'task', or 'email'. Case-insensitive.

contactId ​

Type: String

Required: Yes

The HubSpot contact ID to associate the engagement with.

properties ​

Type: Object

Required: Yes

Engagement-specific fields. Example: { hs_note_body }, { hs_call_status, hs_call_body }, etc.

timestamp ​

Type: Number or String

Required: No

Optional. Timestamp (UNIX ms or ISO 8601 string) for the engagement. Auto-applied as 'hs_timestamp' if not already set.

customRequestProperties ​

Type: Object

Required: No

Optional. Additional request configuration (e.g., headers, timeouts).

Output ​

Type: Promise

Returns a Promise resolving to:

  • status: true if the engagement was created and associated successfully
  • data: Engagement object returned by HubSpot
  • err: Error message if creation or association failed

$io.hubspot.createNoteForContact ​

Create a note engagement and associate it with a HubSpot contact.

Usage ​

js
$io.hubspot.createNoteForContact(connectionName, contactId, body, timestamp, customRequestProperties)

Description ​

Creates a Note engagement and associates it with the specified HubSpot contact. The note body is passed as hs_note_body.

The optional timestamp sets the engagement time (UNIX ms or ISO). Defaults to now if omitted.

Usage Scenarios ​

  • Log internal notes related to a contact
  • Store comments, updates, or remarks from your CRM or support system
  • Automate creation of engagement notes after actions or events

Parameters ​

connectionName ​

Type: String

Required: Yes

HubSpot connection name.

contactId ​

Type: String

Required: Yes

HubSpot contact ID.

body ​

Type: String

Required: Yes

Text content of the note.

timestamp ​

Type: Number or String

Required: No

Optional timestamp of the note.

customRequestProperties ​

Type: Object

Required: No

Optional advanced request options.

Output ​

Type: Promise

Returns { status, data, err } — engagement info or error message.

$io.hubspot.createTaskForContact ​

Create a task engagement and associate it with a HubSpot contact.

Usage ​

js
$io.hubspot.createTaskForContact(connectionName, contactId, subject, status, timestamp, customRequestProperties)

Description ​

Creates a Task engagement in HubSpot and links it to the specified contact using their HubSpot contact ID.

  • subject maps to the hs_task_subject field and represents the name or description of the task.
  • status indicates the task's state. Default is NOT_STARTED. Common valid values include:
    • NOT_STARTED, IN_PROGRESS, WAITING, DEFERRED, COMPLETED

A timestamp (UNIX epoch ms or ISO 8601 string) can be optionally provided to specify when the task engagement was created.

Internally, this function uses $io.hubspot.createEngagementForContact with type task.

Usage Scenarios ​

  • Assign follow-up actions to a contact
  • Track to-do items or reminders related to sales/support
  • Automate task creation after specific workflows or events

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

contactId ​

Type: String

Required: Yes

The HubSpot contact ID to associate the task with.

subject ​

Type: String

Required: Yes

The task title or subject (mapped to 'hs_task_subject').

status ​

Type: String

Required: No

Optional. Status of the task (default: 'NOT_STARTED').

timestamp ​

Type: Number or String

Required: No

Optional. Timestamp of the task engagement (UNIX ms or ISO string).

customRequestProperties ​

Type: Object

Required: No

Optional. Advanced request options (e.g., headers, timeouts).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the task was created and associated successfully
  • data: The created engagement object (task)
  • err: Error message if the request failed

$io.hubspot.deleteContact ​

Delete a HubSpot contact by ID.

Usage ​

js
$io.hubspot.deleteContact(connectionName, contactId, customRequestProperties)

Description ​

Deletes a contact from HubSpot using the /crm/v3/objects/contacts/{contactId} endpoint.

This performs a hard delete — the contact will be permanently removed from the CRM.

Use this function with caution, especially in production environments. You can pass optional customRequestProperties to supply headers, authentication overrides, or timeout settings.

Usage Scenarios ​

  • Remove test contacts or duplicates
  • Support user-triggered deletions from your app
  • Implement contact lifecycle cleanup or GDPR erasure

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

contactId ​

Type: String

Required: Yes

The unique ID of the contact to delete.

customRequestProperties ​

Type: Object

Required: No

Optional. Additional request options such as headers or timeouts.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the contact was deleted
  • data: HubSpot API deletion response (may be empty)
  • err: Error message if the deletion failed

$io.hubspot.execApiRequest ​

Execute any HubSpot API endpoint dynamically using raw path and method.

Usage ​

js
$io.hubspot.execApiRequest(connectionName, path, method, data, queryParams, customProps)

Description ​

This function allows low-level execution of any HubSpot API request using the given connection. It is useful when the desired functionality is not yet wrapped in a higher-level method.

This method validates the connection and forwards the request to the appropriate plugin instance using the configured OAuth2 token.

Request routing logic:

  • data is used as the request body (for POST, PATCH, PUT).
  • queryParams are serialized as the query string.
  • customProps allows additional fields like headers, timeouts, etc.
  • For GET requests, data is merged into queryParams.

Note: You must ensure the path, method, and payload align with HubSpot’s public API: https://developers.hubspot.com/docs/api/overview

Usage Scenarios ​

  • Perform advanced or uncommon operations with custom headers or query strings

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

path ​

Type: String

Required: Yes

The relative HubSpot API endpoint path (e.g., '/crm/v3/objects/contacts').

method ​

Type: String

Required: Yes

HTTP method for the request. Examples: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'.

data ​

Type: Object

Required: Yes

Payload to send in the request body. Ignored for GET/DELETE unless required explicitly.

queryParams ​

Type: Object

Required: No

Optional. Query string parameters to include in the request URL.

customProps ​

Type: Object

Required: No

Optional. Additional request properties (e.g., headers, timeout). These are passed directly to the underlying SDK.

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the API call was successful
  • data: HubSpot API response body
  • err: Error message or exception string if the request failed

$io.hubspot.getContactByEmail ​

Find a HubSpot contact by exact email address.

Usage ​

js
$io.hubspot.getContactByEmail(connectionName, email, contactProperties, customRequestProperties)

Description ​

This function finds a single HubSpot contact by exact email match using $io.hubspot.searchContacts.

It limits results to 1 and returns only the first match in resp.data for convenience.

You can control the fields returned by specifying contactProperties (array of field names), such as:

js
['firstname', 'lastname', 'phone']

Note: This performs an exact match using operator EQ. It will not return partial matches or aliases.

Optional customRequestProperties allows you to pass headers, timeouts, or other API settings.

Usage Scenarios ​

  • Quickly locate a contact record using an email
  • Look up users by email during authentication or onboarding
  • Build email-based CRM integrations

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

email ​

Type: String

Required: Yes

The email address to search for (exact match).

contactProperties ​

Type: Array of String

Required: No

Optional. List of contact fields to include in the result.

customRequestProperties ​

Type: Object

Required: No

Optional. Advanced request options (e.g., headers, timeouts).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if a contact was found
  • data: A single contact object (or null if not found)
  • err: Error message if search failed

$io.hubspot.getContactById ​

Retrieve a single HubSpot contact by its ID, optionally selecting specific fields.

Usage ​

js
$io.hubspot.getContactById(connectionName, contactId, contactProperties, customRequestProperties)

Description ​

Fetches a specific HubSpot contact by its unique ID using the /crm/v3/objects/contacts/{contactId} endpoint.

You can optionally provide a list of fields (properties) to retrieve using contactProperties:

js
['firstname', 'email', 'phone']

If no properties are specified, HubSpot will return only the default properties.

This method wraps the request to include the properties in the query string via properties=.

You can also pass additional request settings through customRequestProperties.

Usage Scenarios ​

  • Fetch full or partial contact details for display or editing
  • Look up a contact record during an automation step
  • Use after creating or listing a contact to get fresh data

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

contactId ​

Type: String

Required: Yes

The unique ID of the HubSpot contact to retrieve.

contactProperties ​

Type: Array of String

Required: No

Optional. List of field names to include in the response. If omitted, returns default properties.

customRequestProperties ​

Type: Object

Required: No

Optional. Advanced request configuration (e.g., headers, timeouts).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the request succeeded
  • data: HubSpot contact object with requested fields
  • err: Error message if retrieval failed

$io.hubspot.getEngagementById ​

Retrieve and normalize a HubSpot engagement (note, call, task, or email) by its ID.

Usage ​

js
$io.hubspot.getEngagementById(connectionName, type, id, properties, customRequestProperties)

Description ​

Retrieves a specific HubSpot engagement (note, call, task, or email) by ID and returns a normalized version of its core fields, along with the raw data.

Supported types:

  • notes
  • calls
  • tasks
  • emails

If the properties argument is omitted, the function will fetch a default minimal set of fields relevant to the specified type.

The response includes:

  • id, createdAt, updatedAt, and archived
  • subject, body, timestamp (or direction for emails)
  • The raw HubSpot object in raw for advanced use

Usage Scenarios ​

  • Fetch details of a specific engagement by ID
  • Extract structured fields such as subject, body, timestamp
  • Wrap HubSpot raw data in a simplified, normalized form

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection in your ioLoop environment.

type ​

Type: String

Required: Yes

The pluralized engagement type: one of 'notes', 'calls', 'tasks', or 'emails'.

id ​

Type: String

Required: Yes

The HubSpot engagement object ID.

properties ​

Type: Array of Strings

Required: No

Optional. Properties to fetch. If omitted, defaults are applied per type.

customRequestProperties ​

Type: Object

Required: No

Optional. Extra options such as headers, timeouts, etc.

Output ​

Type: Promise

Returns a Promise resolving to:

  • status: true if fetch was successful
  • data: Normalized engagement object (plus raw HubSpot payload in 'raw')
  • err: Error string if applicable

$io.hubspot.listAllEngagementsForContact ​

List all types of engagements (notes, calls, tasks, emails) associated with a HubSpot contact in a grouped format.

Usage ​

js
$io.hubspot.listAllEngagementsForContact(connectionName, contactId, expandDetails, afterMap, limitPerType, customRequestProperties)

Description ​

Fetches and groups all four engagement types — notes, calls, tasks, and emails — associated with the specified contact.

Each group is retrieved via listEngagementsForContact and returned under a key corresponding to the type.

The afterMap object allows independent pagination for each type:

js
{
  notes: 'cursor1',
  calls: 'cursor2',
  ...
}

If expandDetails = true, the method will include full engagement metadata instead of just IDs.

Usage Scenarios ​

  • Retrieve all engagement types for a contact in one call
  • Paginate separately by type using the afterMap token
  • Efficiently group engagement results by category

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection to use.

contactId ​

Type: String

Required: Yes

The HubSpot ID of the contact.

expandDetails ​

Type: Boolean

Required: No

Optional. If true, fetch full engagement data for each ID using getEngagementById.

afterMap ​

Type: Object

Required: No

Optional. A map of pagination cursors per type (e.g., { notes: 'abc', emails: 'def' }).

limitPerType ​

Type: Number

Required: No

Optional. Max number of results to retrieve per engagement type. Default is 10.

customRequestProperties ​

Type: Object

Required: No

Optional. Additional options passed to the underlying HubSpot API requests.

Output ​

Type: Promise

Promise resolving to:

  • status: true
  • data: an object grouped by type (notes, calls, tasks, emails), each containing { results, next, err? }

$io.hubspot.listContactsByDate ​

List HubSpot contacts between the specified date range

Usage ​

js
$io.hubspot.listContactsByDate(connectionName, fromDate, toDate, limit, after, properties, customRequestProperties)

Description ​

Returns a list of contacts created between the provided fromDate and toDate (both inclusive). The fromDate and toDate can be a Moment object, JavaScript Date object, or ISO 8601 string. You may omit either one of the fromDate or toDate parameters by passing null or an empty string. Both fromDate and toDate cannot be ommitted together.

The query uses the createdate >= fromDate and/or createdate <= toDate filter internally

You can optionally pass a list of properties to fetch per contact. By default, the returned properties are: ['firstname', 'lastname', 'email', 'createdate'].

Pagination is supported using the after parameter, which corresponds to paging.next.after from a previous result.

Usage Scenarios ​

  • Fetch all contacts created within a specific date range for syncing
  • Perform incremental data sync from HubSpot
  • Backfill contact records for analytics or CRM updates

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in your app.

fromDate ​

Type: String | Date | moment

Required: Yes

A valid date or timestamp indicating the start of the range (inclusive). Must be ISO string, JS Date, or moment object. Can be null if only toDate is specified.

toDate ​

Type: String | Date | moment

Required: Yes

A valid date or timestamp indicating the end of the range (inclusive). Must be ISO string, JS Date, or moment object. Can be null if only fromDate is specified.

limit ​

Type: Number

Required: No

Maximum number of contacts to return. Default is 20.

after ​

Type: String

Required: No

Pagination cursor for the next page, from a previous response's paging.next.after.

properties ​

Type: Array of Strings

Required: No

Optional list of contact properties to retrieve. Defaults to ['firstname', 'lastname', 'email', 'createdate'].

customRequestProperties ​

Type: Object

Required: No

Optional advanced options like headers, timeouts, etc., passed to the underlying request.

Output ​

Type: Promise

Returns a Promise resolving to:

  • status: true if request succeeded
  • data: { results: [...], paging: { next: { after } } }
  • err: Error message if the request fails

$io.hubspot.listContactsWithEngagementsByDate ​

List contacts with associated engagements within the specified date range.

Usage ​

js
$io.hubspot.listContactsWithEngagementsByDate(connectionName, fromDate, toDate, maxContacts, after, maxEngagementsPerType, properties, customRequestProperties)

Description ​

This function retrieves a list of contacts whose hs_lastengagementdate is within the specified fromDate and toDate range, and includes their associated engagements of all types (notes, calls, emails, tasks).

The fromDate and toDate must be a valid ISO string, JavaScript Date, or moment object. You may omit either one of the fromDate or toDate parameters by passing null or an empty string. Both fromDate and toDate cannot be ommitted together. The function paginates through contacts using the optional after cursor.

Each contact entry includes an engagements object grouping results by type.

The number of contacts and the number of engagements per type are controlled via maxContacts and maxEngagementsPerType respectively.

Usage Scenarios ​

  • Audit recent contact activity in CRM
  • Build reports or dashboards based on recent interactions
  • Analyze recent customer engagement trends

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

fromDate ​

Type: String | Date | moment

Required: Yes

A valid date or timestamp indicating the start of the range (inclusive). Must be ISO string, JS Date, or moment object. The filter is based on hs_lastengagementdate.

toDate ​

Type: String | Date | moment

Required: Yes

A valid date or timestamp indicating the end of the range (inclusive). Must be ISO string, JS Date, or moment object. The filter is based on hs_lastengagementdate.

maxContacts ​

Type: Number

Required: No

Maximum number of contacts to retrieve. Default is 50.

after ​

Type: String

Required: No

Cursor token for pagination. Use paging.next.after from a previous call.

maxEngagementsPerType ​

Type: Number

Required: No

Maximum number of engagements to retrieve per type. Default is 10.

properties ​

Type: Array of Strings

Required: No

Optional list of contact fields to retrieve. Defaults to ['firstname', 'lastname', 'email', 'createdate', 'hs_lastengagementdate'].

customRequestProperties ​

Type: Object

Required: No

Optional advanced request options such as headers or timeouts, passed through to API calls.

Output ​

Type: Promise

Returns a Promise resolving to an object with:

  • status: true if successful
  • data: {results: Array of { contact, engagements } entries, next: Pagination cursor if more results exist}
  • err: Error message if failed

$io.hubspot.listEngagementsForContact ​

List all engagements (notes, calls, tasks, or emails) associated with a given HubSpot contact.

Usage ​

js
$io.hubspot.listEngagementsForContact(connectionName, contactId, type, expandDetails, after, limit, customRequestProperties)

Description ​

Retrieves engagements (e.g., notes, calls, tasks, or emails) associated with the specified contact.

Supported type values:

  • notes
  • calls
  • tasks
  • emails

By default, the response contains only basic engagement IDs. If expandDetails = true, this method will also retrieve full engagement objects via getEngagementById and replace the results array with normalized details.

Pagination is supported via the after token and limit.

Usage Scenarios ​

  • Fetch all notes or calls linked to a specific contact
  • Paginate through a contact's associated tasks or emails
  • Optionally retrieve detailed engagement metadata for display or analysis

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the configured HubSpot connection.

contactId ​

Type: String

Required: Yes

The HubSpot contact ID whose engagements are to be listed.

type ​

Type: String

Required: Yes

The pluralized engagement type: one of 'notes', 'calls', 'tasks', or 'emails'.

expandDetails ​

Type: Boolean

Required: No

Optional. If true, fetch full engagement objects for each associated ID using getEngagementById.

after ​

Type: String

Required: No

Optional. Pagination cursor to fetch the next page of results.

limit ​

Type: Number

Required: No

Optional. Number of results to fetch. Default is 10.

customRequestProperties ​

Type: Object

Required: No

Optional. Extra options like headers, timeouts, etc.

Output ​

Type: Promise

Returns a Promise resolving to:

  • status: true if retrieval was successful
  • data: { results: [ {id or full engagement} ], paging: { next } }
  • err: Error message if applicable

$io.hubspot.retrieveContacts ​

List CRM contacts from HubSpot with pagination and optional field selection.

Usage ​

js
$io.hubspot.retrieveContacts(connectionName, limit, pageAfter, contactProperties, customRequestProperties)

Description ​

This function retrieves a paginated list of contacts from HubSpot CRM using the /crm/v3/objects/contacts endpoint.

You can control:

  • limit: How many results to fetch per page (max 100 recommended).
  • pageAfter: A pagination token (from previous response's paging.next.after).
  • contactProperties: List of specific fields to return for each contact (e.g., ['email', 'phone', 'firstname']).
  • customRequestProperties: Additional API options such as headers, timeouts, or authentication overrides.

This is a thin wrapper around $io.hubspot.execApiRequest, preconfigured to target the standard contacts endpoint with a GET method.

Usage Scenarios ​

  • Fetch basic or detailed contact data for CRM synchronization
  • Paginate through large HubSpot contact lists
  • Retrieve only selected contact properties (e.g., email, phone)

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

limit ​

Type: Number

Required: No

Optional. Number of contacts to retrieve in a single page (default is 10).

pageAfter ​

Type: String

Required: No

Optional. Token to fetch the next page of contacts from a previous response.

contactProperties ​

Type: Array of String

Required: No

Optional. Specific fields to include for each contact. Example: ['firstname', 'email', 'phone'].

customRequestProperties ​

Type: Object

Required: No

Optional. Additional request configuration (e.g., custom headers or timeout overrides).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the request succeeded
  • data: Raw response from HubSpot, including contact list and optional paging
  • err: Error string if the request failed

$io.hubspot.searchContacts ​

Search for HubSpot contacts using filters and return matching records.

Usage ​

js
$io.hubspot.searchContacts(connectionName, filters, contactProperties, limit, customRequestProperties)

Description ​

This function searches HubSpot contacts using flexible filter criteria via the /crm/v3/objects/contacts/search endpoint.

The filters object maps field names to either:

  • A direct value (defaults to 'EQ' operator)
  • An object with operator and value

Examples:

js
{
  email: "[email protected]", // interpreted as { operator: "EQ", value: "[email protected]" }
  firstname: { operator: "CONTAINS", value: "Jane" },
  createdate: { operator: "GT", value: "2023-01-01" }
}

Supported operators include:

  • EQ, NEQ, GT, GTE, LT, LTE
  • CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH
  • IN, NOT_IN
  • BETWEEN, HAS_PROPERTY

Specify which contact fields to return using contactProperties (array of strings). Limit results using limit (default 10, max 100).

Internally, the function constructs a single filter group. For complex AND/OR logic, use the HubSpot API directly via $io.hubspot.execApiRequest.

Usage Scenarios ​

  • Find contacts by email, name, or custom field values
  • Build contact lookup features in your app
  • Implement dynamic CRM filtering for users

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

filters ​

Type: Object

Required: Yes

Key-value pairs representing filter conditions. Each value can be a direct match or an object with { operator, value }.

contactProperties ​

Type: Array of String

Required: No

Optional. List of fields to return for each matched contact.

limit ​

Type: Number

Required: No

Optional. Maximum number of results to return (default: 10, max: 100).

customRequestProperties ​

Type: Object

Required: No

Optional. Additional request options (e.g., headers, timeouts).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the request succeeded
  • data: HubSpot API response with matching contacts and metadata
  • err: Error message if the search failed

$io.hubspot.updateContact ​

Update an existing HubSpot contact with new or modified properties.

Usage ​

js
$io.hubspot.updateContact(connectionName, contactId, properties, customRequestProperties)

Description ​

Updates an existing contact in HubSpot using the /crm/v3/objects/contacts/{contactId} endpoint.

You must pass an object containing only the contact fields to update — do not wrap your input in a properties key.

Correct:

js
{
  email: "[email protected]",
  phone: "+1-555-1234"
}

Incorrect (do NOT wrap in properties):

js
{
  properties: {
    email: "[email protected]"
  }
}

The method will internally wrap your input as:

json
{
  "properties": { ...your input... }
}

Optional customRequestProperties can be used to pass headers, timeouts, or other advanced API settings.

Usage Scenarios ​

  • Edit contact details from your app
  • Sync external profile changes into HubSpot
  • Apply enrichment data to an existing CRM contact

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the HubSpot connection configured in the ioLoop app.

contactId ​

Type: String

Required: Yes

The unique ID of the HubSpot contact to update.

properties ​

Type: Object

Required: Yes

Key-value pairs of contact fields to update. Do NOT include a top-level 'properties' key — this function adds it automatically.

customRequestProperties ​

Type: Object

Required: No

Optional. Advanced request options (e.g., headers, timeouts).

Output ​

Type: Promise

Returns a Promise resolving to an object:

  • status: true if the contact was successfully updated
  • data: HubSpot API response with updated contact metadata
  • err: Error message if the update failed