Import users into any HubSpot account from an external app

Learn how to set up the User import source feature to register your public app as a data source for bulk user imports. This means customers who have installed your app in their HubSpot account can use it to bulk import users. This feature is only available for public apps.

Set up the User import source feature

 Before you configure your app to use the User import source feature, you'll need to set up and host two API endpoints that will accept POST requests from HubSpot when a customer who's installed your app triggers a bulk user import. 

One endpoint you set up will be to return account data, while the other will return user data. The specifications for each endpoint are detailed in the sections below.

Requests are sent with the HubSpot Signature. To ensure that the requests that are received are from HubSpot, they can be validated using the signature: https://developers.hubspot.com/docs/api/webhooks/validating-requests

Endpoint to return account data

The URL of the endpoint that returns account data should be structured like https://BASE_PATH_OF_YOUR_SERVICE/feature/USER_IMPORT/event/FETCH_ACCOUNTS.

HubSpot wil provide the following fields in the body of the request: 

{"portalId":10,"appId":20}

The response you return when HubSpot makes a POST request to the endpoint should be a JSON-formatted object with the following fields:

{ "portalId": 10, "appId": 20, "integrationComponentIdentifier": "USER_IMPORT", "eventType": "FETCH_ACCOUNTS", "payload": { "accounts": [ { "id": "testId1", "name": "testAccount1" }, { "id": "testId2", "name": "testAccount2" } ] } }

Endpoint to return user data

The URL of the endpoint that returns account data should be structured like https://BASE_PATH_OF_YOUR_SERVICE/feature/USER_IMPORT/event/FETCH_USERS.

HubSpot wil provide the following fields in the body of the request: 

{ "portalId": 10, "appId": 20, }

The response you return when HubSpot makes a POST request to the endpoint should be a JSON-formatted object with the following fields:

{ "portalId": 10, "appId": 20, "integrationComponentIdentifier": "USER_IMPORT", "eventType": "FETCH_USERS", "payload": { "users": [ { "id": "testUser1", "email": "testuser1-invalid@hubspot.com", "firstName": "Test", "lastName": "User-One", "existingUserId": null }, { "id": "testUser2", "email": "testuser2-invalid@hubspot.com", "firstName": "Test", "lastName": "User-Two", "existingUserId": null }, { "id": "testUser3", "email": "testuser3-invalid@hubspot.com", "firstName": "Test", "lastName": "User-Three", "existingUserId": null } ] } }
Once you've set up your two endpoints, you can configure your app settings. 
  • In your app developer account, navigate to apps in the main navigation bar.
  • Select the app. 
  • Click the Auth tab. 
  • In the Scopes section, click Add new scope. 
  • In the right panel, select the settings.users.write scope and click Update. 
  • Click Save changes. 
  • In the left sidebar, click More features. 
  • In the Target URL section, enter the URL that HubSpot will make a POST request to when events trigger. Or, use this testing URL: https://api.hubspot.com/integration-components-example/v1/sample-app-webhooks/beta-app
  • Click to toggle the User import source switch on. 
  • Click Save changes. 
app-features-user-import

Test the functionality

After setting up your two endpoints and configuring your app settings, you can test your endpoints out: 

  • Install your app.
  • In your HubSpot account, click the settings icon in the top navigation bar.
  • In the left sidebar menu, navigate to Users & Teams.
  • Click Create user. 
  • In the Or create multiple users at once section, click your app to begin the import process. 
  • Follow the steps in this article to import and set up your users. 
import-users-1
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.