{"id":28558041,"url":"https://github.com/HubSpot/hubspot-api-nodejs","last_synced_at":"2025-06-10T08:04:18.892Z","repository":{"id":37963883,"uuid":"236127880","full_name":"HubSpot/hubspot-api-nodejs","owner":"HubSpot","description":"HubSpot API NodeJS Client Libraries for V3 version of the API","archived":false,"fork":false,"pushed_at":"2025-05-20T14:44:01.000Z","size":39607,"stargazers_count":353,"open_issues_count":41,"forks_count":113,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-26T23:39:52.681Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HubSpot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-25T05:03:49.000Z","updated_at":"2025-05-24T06:21:57.000Z","dependencies_parsed_at":"2024-02-21T13:42:49.321Z","dependency_job_id":"fab6d92e-6411-48f8-85ea-602ca330a425","html_url":"https://github.com/HubSpot/hubspot-api-nodejs","commit_stats":{"total_commits":576,"total_committers":20,"mean_commits":28.8,"dds":0.4652777777777778,"last_synced_commit":"67880218805e87cc115f7241943440ca3d76a99c"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2Fhubspot-api-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2Fhubspot-api-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2Fhubspot-api-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2Fhubspot-api-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HubSpot","download_url":"https://codeload.github.com/HubSpot/hubspot-api-nodejs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2Fhubspot-api-nodejs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":257136786,"owners_count":22494948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-10T08:02:36.583Z","updated_at":"2025-06-10T08:04:18.884Z","avatar_url":"https://github.com/HubSpot.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# hubspot-api-nodejs\n\nNodeJS v3 [HubSpot API](https://developers.hubspot.com/docs/api/overview) SDK(Client) files\n\n## Sample apps\n\nPlease, take a look at our [Sample apps](https://github.com/HubSpot/sample-apps-list)\n\n## Available SDK methods reference\n\n[Available SDK methods reference](https://github.hubspot.com/hubspot-api-nodejs/)\n\n## Installing\n\n```shell\nnpm install @hubspot/api-client\n```\n\n## Instantiate client\n\n```javascript\nconst hubspot = require('@hubspot/api-client')\nconst hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN })\n```\n\n\u003e [!NOTE]\n\u003e Please note that all code examples are written in JavaScript. Some of them won’t work in Typescript without changes.\n\nFor ES modules\n\n```javascript\nimport { Client } from \"@hubspot/api-client\";\nconst hubspotClient = new Client({ accessToken: YOUR_ACCESS_TOKEN });\n```\n\nYou'll need to create a [private app](https://developers.hubspot.com/docs/api/private-apps) to get your access token or you can obtain [OAuth2 access token](https://developers.hubspot.com/docs/api/working-with-oauth).\n\nYou can provide developer API key. There is no need to create separate client instances for using endpoints with API key and Developer API key support.\n\n```javascript\nconst hubspotClient = new hubspot.Client({ developerApiKey: YOUR_DEVELOPER_API_KEY })\n```\n\n```javascript\nconst hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN, developerApiKey: YOUR_DEVELOPER_API_KEY })\n```\n\nTo change the base path:\n\n```javascript\nconst hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN, basePath: 'https://some-url' })\n```\n\nTo add custom headers to all request:\n\n```javascript\nconst hubspotClient = new hubspot.Client({\n    accessToken: YOUR_ACCESS_TOKEN,\n    defaultHeaders: { 'My-header': 'test-example' },\n})\n```\n\nIf you're an app developer, you can also instantiate a client and obtain a new accessToken with your app\ndetails and a refresh_token:\n\n```javascript\nhubspotClient.oauth.tokensApi\n    .create('refresh_token', undefined, undefined, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REFRESH_TOKEN)\n    .then((results) =\u003e {\n        console.log(results)\n\n        // this assigns the accessToken to the client, so your client is ready\n        // to use\n        hubspotClient.setAccessToken(results.accessToken)\n\n        return hubspotClient.crm.companies.basicApi.getPage()\n    })\n```\n\n### Rate limiting\n\n[Bottleneck](https://github.com/SGrondin/bottleneck) is used for rate limiting. To turn on/off rate limiting use `limiterOptions` option on Client instance creation. Bottleneck options can be found [here](https://github.com/SGrondin/bottleneck#constructor).\nPlease note that Apps using OAuth are only subject to a limit of 100 requests every 10 seconds. Limits related to the API Add-on don't apply.\n\n```javascript\nconst hubspotClient = new hubspot.Client({\n    accessToken: YOUR_ACCESS_TOKEN,\n    limiterOptions: DEFAULT_LIMITER_OPTIONS,\n})\n```\n\nDefault settings for the limiter are:\n\n```javascript\nconst DEFAULT_LIMITER_OPTIONS = {\n    minTime: 1000 / 9,\n    maxConcurrent: 6,\n    id: 'hubspot-client-limiter',\n}\n```\n\nSearch settings for the limiter are:\n\n```javascript\nconst SEARCH_LIMITER_OPTIONS = {\n    minTime: 550,\n    maxConcurrent: 3,\n    id: 'search-hubspot-client-limiter',\n}\n```\n\n### Retry mechanism\n\nIt's possible to turn on retry for failed requests with statuses 429 or 5xx. To turn on/off configurable retries use `numberOfApiCallRetries` option on Client instance creation. `numberOfApiCallRetries` can be set to a number from 0 - 6. If `numberOfApiCallRetries` is set to a number greater than 0 it means that if any API Call receives ISE5xx this call will be retried after a delay 200 * retryNumber ms and if 429 (Rate limit is exceeded) is returned for \"TEN_SECONDLY_ROLLING\" the call will be retried after a delay 10 sec. Number of retries will not exceed `numberOfApiCallRetries` value.\n\n```javascript\nconst hubspotClient = new hubspot.Client({\n    accessToken: YOUR_ACCESS_TOKEN,\n    numberOfApiCallRetries: 3,\n})\n```\n\n## Usage\n\nAll methods return a [promise]. The success includes the serialized to JSON body and response objects. Use the API method via:\n\n```javascript\nhubspotClient.crm.contacts.basicApi\n    .getPage(limit, after, properties, propertiesWithHistory, associations, archived)\n    .then((results) =\u003e {\n        console.log(results)\n    })\n    .catch((err) =\u003e {\n        console.error(err)\n    })\n```\n\n[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise\n\n### {EXAMPLE} Create Contact, Company and associate created objects\n\n```javascript\nconst contactObj = {\n    properties: {\n        firstname: yourValue,\n        lastname: yourValue,\n    },\n}\nconst companyObj = {\n    properties: {\n        domain: yourValue,\n        name: yourValue,\n    },\n}\n\nconst createContactResponse = await hubspotClient.crm.contacts.basicApi.create(contactObj)\nconst createCompanyResponse = await hubspotClient.crm.companies.basicApi.create(companyObj)\nawait hubspotClient.crm.associations.v4.basicApi.create(\n    'companies',\n    createCompanyResponse.id,\n    'contacts',\n    createContactResponse.id,\n    [\n        {\n              \"associationCategory\": \"HUBSPOT_DEFINED\",\n              \"associationTypeId\": AssociationTypes.companyToContact\n              // AssociationTypes contains the most popular HubSpot defined association types\n        }\n    ]\n)\n```\n\n### {EXAMPLE} Get associated Companies by Contact\n\n```javascript\nconst companies = await hubspotClient.crm.associations.v4.basicApi.getPage(\n    'contact',\n    hubspotContactId,\n    'company',\n    after,\n    pageSize,\n  );\n```\n\n### {EXAMPLE} Update multiple objects in batch mode\n\n```javascript\nconst dealObj = {\n    id: yourId,\n    properties: {\n        amount: yourValue,\n    },\n}\n\nconst dealObj2 = {\n    id: yourId,\n    properties: {\n        amount: yourValue,\n    },\n}\n\nawait hubspotClient.crm.deals.batchApi.update({ inputs: [dealObj, dealObj2] })\n```\n\n### {EXAMPLE} Import Contacts\n\n```javascript\nconst fs = require('fs')\n\nconst fileName = 'test.csv'\n\nconst file = {\n    data: fs.createReadStream(fileName),\n    name: fileName,\n};\n\nconst importRequest = {\n    name: 'import(' + fileName + ')',\n    files: [\n        {\n            fileName: fileName,\n            fileImportPage: {\n                hasHeader: true,\n                columnMappings: [\n                    {\n                        columnName: 'First Name',\n                        propertyName: 'firstname',\n                        columnObjectType: 'CONTACT',\n                    },\n                    {\n                        columnName: 'Email',\n                        propertyName: 'email',\n                        columnObjectType: 'CONTACT',\n                    },\n                ],\n            },\n        },\n    ],\n}\n\nconst response = await  hubspotClient.crm.imports.coreApi.create(file, JSON.stringify(importRequest));\n\nconsole.log(response)\n```\n\n### CRM Search\n\nOnly 3 `FilterGroups` with max 3 `Filters` are supported.\n\nDespite `sorts` is an array, however, currently, only one sort parameter is supported.\n\nIn JS `sorts` it's possible to set as:\n\n1. \u003c propertyName \u003e - returned results will be sorted by provided property name in 'ASCENDING' order. e.g: `'hs_object_id'``\n2. \u003c direction \u003e - returned results will be sorted by provided property name and sort direction. e.g: `{ propertyName: 'hs_object_id', direction: 'ASCENDING' }` or `{ propertyName: 'hs_object_id', direction: 'DESCENDING' }`\n\nIn TS `sorts` it's possible to set as:\n\n1. \u003c propertyName \u003e - returned results will be sorted by provided property name in 'ASCENDING' order. e.g: `['hs_object_id']`\n2. \u003c direction \u003e - use `[\"-createdate\"]` to sort in desc and sorts: `[\"createdate\"]` in asc order.\n\n`after` for initial search should be set as 0\n\n### {EXAMPLE} Search CRM Contacts\n\nExample for JS:\n\n```javascript\nconst publicObjectSearchRequest = {\n    filterGroups: [\n    {\n        filters: [\n        {\n            propertyName: 'createdate',\n            operator: 'GTE',\n            value: `${Date.now() - 30 * 60000}`\n        }\n        ]\n    }\n    ],\n    sorts: [{ propertyName: 'createdate', direction: 'DESCENDING' }],\n    properties: ['createdate', 'firstname', 'lastname'],\n    limit: 100,\n    after: 0,\n}\n\nconst response = await hubspotClient.crm.contacts.searchApi.doSearch(publicObjectSearchRequest)\n\nconsole.log(response)\n```\n\nExample for TS:\n\n```Typescript\nconst objectSearchRequest: PublicObjectSearchRequest = {\n    filterGroups: [\n        {\n            filters: [\n                {\n                propertyName: \"createdate\",\n                operator: \"GTE\",\n                value: \"1615709177000\",\n                },\n            ],\n        },\n    ],\n    sorts: [\"-createdate\"],\n    properties: [\"email\", \"createdate\"],\n    limit: 100,\n    after: '0',\n};\n\nconst response = await hubspotClient.crm.contacts.searchApi.doSearch(objectSearchRequest);\n\nconsole.log(response)\n```\n\n### Get all\n\ngetAll method is available for all major objects (Companies, Contacts, Deals, LineItems, Products, Quotes \u0026 Tickets) and works like\n\n```javascript\nconst allContacts = await hubspotClient.crm.contacts.getAll()\n```\n\n\u003e [!NOTE]\n\u003e Please note that pagination is used under the hood to get all results.\n\n### Upload a file (via the SDK)\n\n```javascript\nconst response = await hubspotClient.files.filesApi.upload(\n    {\n        data: fs.createReadStream('./photo.jpg'),\n        name: 'photo.jpg'\n    },\n    undefined,\n    '/folder',\n    'photo.jpg',\n    undefined,\n    JSON.stringify({\n        access: 'PRIVATE',\n        overwrite: false,\n        duplicateValidationStrategy: 'NONE',\n        duplicateValidationScope: 'ENTIRE_PORTAL',\n    })\n)\n\nconsole.log(response)\n```\n\n### OAuth\n\n#### Obtain your authorization url\n\n```javascript\nconst clientId = 'your_client_id'\nconst redirectUri = 'take_me_to_the_ballpark'\nconst scope = 'some scopes'\nconst uri = hubspotClient.oauth.getAuthorizationUrl(clientId, redirectUri, scope)\n```\n\n#### Obtain an access token from an authorization_code\n\n```javascript\nreturn hubspotClient.oauth.tokensApi.create(\n        'authorization_code',\n        code, // the code you received from the oauth flow\n        YOUR_REDIRECT_URI,\n        YOUR_CLIENT_ID,\n        YOUR_CLIENT_SECRET,\n    ).then(...)\n```\n\n### CMS\n\n#### Get audit logs\n\n```javascript\nconst response = await hubspotClient.cms.auditLogs.auditLogsApi.getPage()\n```\n\n## Not wrapped endpoint(s)\n\nIt is possible to access the hubspot request method directly,\nit could be handy if client doesn't have implementation for some endpoint yet.\nExposed request method benefits by having all configured client params.\n\n```javascript\nhubspotClient.apiRequest({\n    method: 'PUT',\n    path: '/some/api/not/wrapped/yet',\n    body: { key: 'value' },\n})\n```\n\n### Get contacts\n\n```javascript\nconst response = await hubspotClient.apiRequest({\n    path: '/crm/v3/objects/contacts',\n})\nconst json = await response.json()\nconsole.log(json)\n```\n\n### Upload a file\n\n```javascript\nconst formData = new FormData();\nconst options = {\n// some options\n};\nformData.append(\"folderPath\", '/');\nformData.append(\"options\", JSON.stringify(options));\nformData.append(\"file\", fs.createReadStream('file path'));\n\nconst response = await hubspotClient.apiRequest({\n    method: 'POST',\n    path: '/filemanager/api/v3/files/upload',\n    body: formData,\n    defaultJson: false\n});\n\nconsole.log(response);\n```\n\n## Reserved words\n\nThe SDK has reserved words(e.g. `from`, `in`, `delete`). [Full list of reserved words.](https://openapi-generator.tech/docs/generators/typescript#reserved-words)\nWhen you face with a reserved word you have to add `_` before the word(e.g. `_from`, `_in`, `_delete`).\n\n```javascript\nconst BatchInputPublicAssociation = {\n    inputs: [\n        {\n            _from: {\n                id : 'contactID'\n            },\n            to: {\n                id: 'companyID'\n            },\n            type: 'contact_to_company'\n        }\n    ]\n};\n\nconst response = await hubspotClient.crm.associations.batchApi.create(\n    'contacts',\n    'companies',\n    BatchInputPublicAssociation\n);\n```\n\n## Typescript\n\nYou may use this library in your Typescript project via:\n\n```typescript\nimport * as hubspot from '@hubspot/api-client'\nconst hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN , developerApiKey: YOUR_DEVELOPER_API_KEY })\n```\n\n## License\n\nApache 2.0\n\n## Contributing\n\nInstall project dependencies with\n\n```bash\nnpm install\n```\n\nYou can run the tests by executing:\n\n```bash\nnpm run test\n```\n\nYou can check the TypeScript code by running:\n\n```bash\nnpm run lint\n```\n\nIf there is a linting error based on formatting, you can run the command below to auto-correct the formatting:\n\n```bash\nnpm run prettier:write\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHubSpot%2Fhubspot-api-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHubSpot%2Fhubspot-api-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHubSpot%2Fhubspot-api-nodejs/lists"}