Actions

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

Client	Purpose
Client	Manage CRM imports: start, monitor, list, retrieve errors, and cancel imports.

---

Client

Manage CRM imports: start, monitor, list, retrieve errors, and cancel imports.

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig	Required	Authentication configuration. Use OAuth 2.0 refresh token grant (recommended), bearer token, or private app legacy API key.
httpVersion	http:HttpVersion	http:HTTP_2_0	HTTP protocol version.
timeout	decimal	30	Maximum wait time for a response in seconds.
retryConfig	http:RetryConfig?	()	Retry configuration for failed requests.
secureSocket	http:ClientSecureSocket?	()	SSL/TLS configuration.
proxy	http:ProxyConfig?	()	Proxy server configuration.
circuitBreaker	http:CircuitBreakerConfig?	()	Circuit breaker configuration.
compression	http:Compression	http:COMPRESSION_AUTO	Compression handling configuration.
validation	boolean	true	Enable or disable payload validation.

Initializing the client

import ballerinax/hubspot.crm.import as crmImport;

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

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

Operations

Import lifecycle

Start a new import

Signature: post .

Starts a new CRM import by uploading a CSV file along with an import request JSON configuration that defines column mappings, object types, and import operations.

Parameters:

Name	Type	Required	Description
payload	Body	Yes	The import payload containing files (with fileContent as byte array and fileName) and importRequest (JSON string defining column mappings and import settings).
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: PublicImportResponse|error

Sample code:

string importRequestJson = check io:fileReadString("resources/contact_import_request.json");
byte[] csvContent = check io:fileReadBytes("resources/contact_import_file.csv");

crmImport:PublicImportResponse response = check importClient->/.post({
    importRequest: importRequestJson,
    files: {
        fileContent: csvContent,
        fileName: "contact_import_file.csv"
    }
});

Sample response:

{
  "id": "48541593",
  "state": "STARTED",
  "createdAt": "2024-10-15T08:30:00.000Z",
  "updatedAt": "2024-10-15T08:30:00.000Z",
  "optOutImport": false,
  "metadata": {
    "counters": {},
    "fileIds": ["98765"],
    "objectLists": []
  },
  "mappedObjectTypeIds": ["0-1"]
}

Get active imports

Signature: get .

Returns a paginated list of all active imports in the HubSpot portal.

Parameters:

Name	Type	Required	Description
queries	GetGetPageQueries	No	Optional query parameters including before, after (paging cursor tokens), and limit (max results per page).
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CollectionResponsePublicImportResponse|error

Sample code:

crmImport:CollectionResponsePublicImportResponse imports = check importClient->/.get();

Sample response:

{
  "results": [
    {
      "id": "48541593",
      "state": "DONE",
      "createdAt": "2024-10-15T08:30:00.000Z",
      "updatedAt": "2024-10-15T08:35:00.000Z",
      "optOutImport": false,
      "metadata": {
        "counters": {"CREATED_OBJECTS": 150, "TOTAL_ROWS": 150, "PROPERTY_VALUES_EMITTED": 450},
        "fileIds": ["98765"],
        "objectLists": [{"listId": "12345", "objectType": "CONTACT"}]
      },
      "importName": "First Contact Data",
      "mappedObjectTypeIds": ["0-1"]
    }
  ],
  "paging": null
}

Import status & errors

Get import information

Signature: get [int importId]

Retrieves detailed information about a specific import, including its current state, metadata counters, and mapped object types.

Parameters:

Name	Type	Required	Description
importId	int	Yes	The ID of the import to retrieve.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: PublicImportResponse|error

Sample code:

crmImport:PublicImportResponse importStatus = check importClient->/[48541593].get();

Sample response:

{
  "id": "48541593",
  "state": "DONE",
  "createdAt": "2024-10-15T08:30:00.000Z",
  "updatedAt": "2024-10-15T08:35:00.000Z",
  "optOutImport": false,
  "metadata": {
    "counters": {"CREATED_OBJECTS": 150, "TOTAL_ROWS": 150, "PROPERTY_VALUES_EMITTED": 450},
    "fileIds": ["98765"],
    "objectLists": [{"listId": "12345", "objectType": "CONTACT"}]
  },
  "importName": "First Contact Data",
  "importSource": "API",
  "mappedObjectTypeIds": ["0-1"]
}

Get import errors

Signature: get [int importId]/errors

Returns a paginated list of errors that occurred during the specified import, with optional row data and error messages.

Parameters:

Name	Type	Required	Description
importId	int	Yes	The ID of the import whose errors to retrieve.
queries	GetImportIdErrorsGetErrorsQueries	No	Optional query parameters: includeRowData (boolean), includeErrorMessage (boolean), limit (int), after (paging cursor).
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: CollectionResponsePublicImportErrorForwardPaging|error

Sample code:

crmImport:CollectionResponsePublicImportErrorForwardPaging errors = check importClient->/[48541593]/errors.get(
    queries = {includeRowData: true, includeErrorMessage: true, limit: 10}
);

Sample response:

{
  "results": [
    {
      "id": "err-001",
      "createdAt": 1697356200,
      "errorType": "INVALID_EMAIL",
      "errorMessage": "The email address 'not-an-email' is not valid.",
      "objectType": "CONTACT",
      "invalidValue": "not-an-email",
      "sourceData": {
        "rowData": ["John", "Doe", "not-an-email"],
        "containsEncryptedProperties": false,
        "lineNumber": 5,
        "fileId": 98765
      }
    }
  ],
  "paging": null
}

Import management

Cancel an active import

Signature: post [int importId]/cancel

Cancels an active import. Only imports in the STARTED or PROCESSING state can be canceled.

Parameters:

Name	Type	Required	Description
importId	int	Yes	The ID of the import to cancel.
headers	map<string|string[]>	No	Optional HTTP headers.

Returns: ActionResponse|error

Sample code:

crmImport:ActionResponse cancelResponse = check importClient->/[48541593]/cancel.post();

Sample response:

{
  "status": "COMPLETE",
  "startedAt": "2024-10-15T08:30:00.000Z",
  "completedAt": "2024-10-15T08:31:00.000Z",
  "links": {}
}