Last modified: September 3, 2025
This feature requires approval from HubSpot to use. If you’re interested in applying to get access to app objects, or if you want to learn more about the functionality, please submit this in-app form.
Learn how to build a proof-of-concept app where you’ll configure an app object that you can test and use in a developer test account.
1

Install the latest version of the HubSpot CLI

You’ll need the latest version of the HubSpot CLI to create a unified app. In a terminal window, run the following command to update your version of the CLI:
npm install -g @hubspot/cli@latest
The CLI needs to be version 7.6.0 or later. You can check which version of the CLI you have by running hs --version.
2

Authenticate your developer account

You’ll then need to authenticate your developer account by running the following command:
hs account auth
  • Follow the prompts to generate a Personal Access Key in your account, then copy and paste it into the terminal to save your configuration.
  • During this beta period, it’s recommended that you make this account your default in the CLI. This will prevent potential errors with access for the account you’ve enrolled in the beta.
3

Create a new boilerplate project

Run the command below in your terminal to create a new project and marketplace app with either the currently compatible features or an app object reference schema.
hs project create --templateSource robrown-hubspot/hubspot-project-components-ua-app-objects-beta
4

Configure the newly created project and upload it to your developer account

The projects framework moves app features that were previously configured in the UI or via the API over to source code files, typically defined as <file-name>-hsmeta.json configuration files.App features are then created using a combination of subfolders from the main /src/app directory and other configuration files as needed. To configure your project:
  • Add one or more valid redirect URLs to the app-hsmeta.json file based on your local (or another non-production) OAuth server configuration.
To get started, you can use the sample OAuth Node.js example and run it locally. It’s already set up to work with https://localhost:3000/oauth-callback as the redirect URL configured in the boilerplate example code from the hs project create command you ran in the previous step.
  • Change the uid property of the app in the app-hsmeta.json file and the other *-hsmeta.json configuration files in your project.
UIDs are used as a unique identifier for all your project’s components and features. Once a feature and UID are created, changing or modifying the UID in subsequent deployments will force the platform to recognize it as different from previous features, which may not be intended.
  • When using app objects for your unified app, only the authorized “name” property definitions will be allowed based on your object request. As part of this private beta, you should have separately received confirmation of your app’s approved “name”, which should be used in the *-object-hsmeta.json configuration. For reference, the fully-qualified name (FQN) for your app object will be a<appId>_<name>. For example, if your appId is 16858319 and your name property was CARS, then your FQN would be a16858319_cars.
  • After you’ve saved your changes, run the hs project upload CLI command to upload your project to the HubSpot developer platform and automatically trigger a new build.
  • In a browser window, navigate to https://app.hubspot.com/developer_projects/<accountId> to visit the projects UI and confirm the app and project have been created, built, and deployed correctly.
5

Add the client ID and client secret of your app to your app

  • After uploading your project, you’ll need to get the auth details for your app to copy over to your OAuth configuration:
    • Click Projects in the Development navigation menu.
    • Click the name of your new project.
    • Click the UID of your app, then click the Auth tab.
    • Copy the Client ID and Client secret from your new app and paste them into the corresponding locations in your local OAuth server’s configuration, then restart your OAuth server.
6

Configure the app object schema configuration

Next you’ll configure your app object schema:
  • Add a new app object by creating a directory within the /src/app directory and name it app-objects. The resulting path to the new directory should be /src/app/app-objects.
  • Create a new configuration file to represent the schema of your object, You should use the object name granted to your app during the preview process as the prefix for the file name, followed by -object-hsmeta.json. For example, in the reference project template, the app object name is “CAR”, so the resulting configuration file is named car-object-hsmeta.json.
  • Consult the app object component definition reference file and customize the fields to the corresponding values for your app object.
    • Within the config object of your definition, the name field must match the name that was granted to your app during the review process, formatted in UPPER_SNAKE_CASE format.
    • Note that once the properties and fields have been added to your app object schema and uploaded to your project in the next step, they cannot be removed.
For convenience during testing, the same app object name can be used across multiple apps to support your development lifecycle. Start with this proof-of-concept app, then as migrations become available, you can use the same name and schema definitions across your development, staging, and production apps. UIDs for each of these instances will need to be unique.
  • When you’re done editing your app object schema definition, and you’re ready to commit these changes, run the following commands to save your changes:
hs project upload
hs project deploy
  • In a browser window, navigate to https://app.hubspot.com/developer_projects/<hubId> to visit the projects UI and confirm the app and project have been created, built, and deployed correctly.
7

Update your app

Now that your app object schema has been uploaded, you’ll need to update the scopes defined in your app-hsmeta.json file to reflect the scopes created from the previous step. These scopes should be visible in the CLI logs after you ran hs project upload.
  • Edit the app-hsmeta.json file and add the new scopes to the array of requiredScopes within the auth definition. For example, if your appId was a12345, then you’d edit the auth definition to the following:
"auth": {
  "type" : "oauth",
  "redirectUrls": ["http://localhost:3000/oauth-callback"],
  "requiredScopes": [
    "crm.objects.contacts.read",
    "crm.objects.contacts.write",
    "crm.app.objects.a12345_my_app_object.view",
    "crm.app.objects.a12345_my_app_object.create",
    "crm.app.objects.a12345_my_app_object.edit",
    "crm.app.schemas.a12345_my_app_object.read",
    "crm.app.objects.a12345_my_app_object.merge",
    "crm.app.objects.a12345_my_app_object.delete",
    "crm.app.schemas.a12345_my_app_object.properties.write"
  ],
  "optionalScopes": [],
  "conditionallyRequiredScopes": []
},
Please note:
  • Customers will only be able to see your app object if the schemas.read scope is included in your app settings, and is requested during the installation/reauthorization OAuth flow. It’s highly recommended including all app object scopes in your settings, but schemas.read is mandatory for customers to be able to access it. For example, for an appId of 12345, you’d include crm.app.schemas.a12345_MY_APP_OBJECT.read as a required scope.
  • Depending on the app you’re testing with (prototype, development, staging, production), you’ll need to be mindful of where you add your scope definitions. Although deploying a production app isn’t yet supported during this phase of the private beta, it’s generally safest to include these scopes as conditionallyRequiredScopes when you’re ready for production. Learn more about these scope types in the public app documentation.
  • When you’re done adding these scopes and you’ve saved your changes, run the following commands to commit your changes to the platform:
hs project upload
hs project deploy
After deployment is complete, your app and the corresponding app object are now ready to test with an installed account.
8

Create a developer test account (optional) and install your app

If don’t already have a test account, you can create one in HubSpot:
  • Navigate to Test accounts in the Development navigation menu, then click Create developer test account. Follow the prompts to create your new test account.
  • In the left sidebar menu, navigate to Projects, click the name of your new project, then click the UID of your app in the component list.
  • On the Auth tab, copy your app’s install link.
  • Use this link to install the app in your developer test account.
  • Open the test account and navigate to the Connected Apps page, where you should see your installed app listed.
  • In your test account, navigate to CRM > Contacts, then click the CRM object dropdown menu and confirm that your app object is available.
  • You can then confirm that your schema definition conforms to your configuration file by creating a new record of your app object.
app-object-available-in-crm
9

Programmatic data access using the HubSpot objects API

Now that you’ve successfully created your app object and you’ve tested it in a developer test account, you can use the OAuth access token associated with the installed test account to make requests to update data in the account directly via the objects API.Read through the objects API for more information on the API, but any requests specific to your app object will follow the same conventions as other standard objects in HubSpot. You’ll need to use your app object’s objectTypeId or fullyQualifiedName as the objectType path parameter in your request.For example, the following code block demonstrates how to make cURL request to create a new record of your app object:
curl --request POST \
  --url https://api.hubapi.com/crm/v3/objects/<fullyQualifiedName> \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'
You can find the objectTypeId for your app object by navigating to the records index page:
  • Navigate to CRM > Contacts in the developer test account that you installed your app.
  • Click the dropdown menu at the top of the page and select your app object.
  • The objectTypeId will appear in the URL between the /objects/<objectTypeId>/views portion.

​
Next steps

Check out the reference documentation for next steps on how to use app objects with different developer platform features: