> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. --- id: c8f90a56-2ab7-40d2-99b7-6708582e151b --- # App objects reference > Reference information for building app objects, including configuration options for your project. 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](https://app.hubspot.com/l/developer-overview/appObjectsEventsRequest). Below, find reference information for developer platform app features with app objects, including configuration file definitions, scopes details, and more. ## Project structure * All project components must live within the `src` directory specified in the `hsproject.json` config file. * All app features and components must live within the `app/` directory. * App objects are defined within the `app-objects/` directory. * App object associations are defined within the `app-object-associations/` directory. * All component and feature instances are declared using `*-hsmeta.json` files. You can use any file name you'd like, as long as it ends in `-hsmeta.json` (e.g., `my-cool-object-hsmeta.json`). These files must live at the root level of their respective folder. ```shell theme={null} project-folder/ └──src/ └── app/ ├── app-hsmeta.json └── app-objects/ └── app-object-hsmeta.json └── app-object-associations/ └── app-object-to-contact-hsmeta.json ``` ## App objects To create an app object, include an `app-objects` component directory in the project, along with a configuration file. ```shell theme={null} project-folder/ └───src/ └── app/ └── app-hsmeta.json └── app-objects/ └── my-cool-object-hsmeta.json ``` Below are the configuration options available for `*-object-hsmeta.json`. ```json theme={null} { "uid": "car-app-object", "type": "app-object", "config": { "name": "CAR", "appPrefix": "Vroom", "description": "An automobile in our warehouse.", "singularForm": "Car", "pluralForm": "Cars", "primaryDisplayLabelPropertyName": "model", "secondaryDisplayLabelPropertyNames": ["make"], "settings": { "hasRecordPage": true, "allowsUserCreatedRecords": true, "hasEngagements": true }, "properties": [ { "type": "string", "fieldType": "text", "name": "model", "label": "Model", "description": "The model of the car" }, { "type": "enumeration", "fieldType": "select", "name": "make", "label": "Make", "description": "The manufacturer of the car.", "options": [ { "label": "Ford", "value": "ford", "displayOrder": 0 }, { "label": "Toyota", "value": "toyota", "displayOrder": 1 }, { "label": "Chevrolet", "value": "chevrolet", "displayOrder": 2 } ] } ] } } ```

Fields marked with \* are required.

| Field | Type | Description | | ------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | String | A unique identifier for the app object. Must be globally unique within the project. | | `type`\* | String | The type of component. Must match the name of the parent folder (`app-object`). | | `name`\* | String | The name of your app object. Use the approved name that you received in your approved app confirmation. Must be uppercase snake case (`MY_OBJECT_NAME`). | | `appPrefix` | String | A string that precedes the singular or plural name of the object in HubSpot's UI to help differentiate it from other objects. In this example, the `appPrefix` of `Vroom` and `singularForm` of `Car` would result in "Vroom Car" displaying in the UI. | | `description`\* | String | the description of the object, which will display in HubSpot. | | `singularForm`\* | String | The singular form of the object name. | | `pluralForm`\* | String | The plural form of the object name. | | `properties`\* | Array | A list of CRM properties defined for the object. Properties are defined using the same fields as the [properties API](/api-reference/latest/crm/properties/guide). The resulting properties will automatically have `a_` prepended to it (e.g., `a12345_make`) on creation. You should not include the prefix in the config file. | | `primaryDisplayLabelPropertyName`\* | String | The name of the property that should be used as the [primary display property](https://knowledge.hubspot.com/object-settings/create-custom-objects#:~:text=object%27s%20singular%20name.-,Primary%20display%20property,-%3A%20the%20property%20used). The value should match the name provided in the `properties` list (i.e., it should not include the generated `a_` prefix.) | | `secondaryDisplayLabelPropertyNames`\* | Array | The list of properties that should be used as [secondary display properties](https://knowledge.hubspot.com/object-settings/create-custom-objects#:~:text=Secondary%20properties%3A). The value should match the name provided in the `properties` list (i.e., it should not include the generated `a_` prefix.) | | `settings`\* | Object | An object containing object settings. | | `hasRecordPage`\* | Boolean | Whether record pages exist for instances of this app object. When set to `false`, the index page will still exist, but it will not include links to individual record pages. | | `allowsUserCreatedRecords`\* | Boolean | Whether end-users will be able to create records using the object. When set to `false`, users will not be able to create records in HubSpot | | `hasEngagements`\* | Boolean | Whether the app object records support activities/engagements. When set to `false`, app object record pages will not include any engagement functionalities, such as the activity tab or activity-related timeline filters. | The fully-qualified name (FQN) for your app object will be `a_`. For example: if your `appId` is `16858319` and the app object name is `CARS`, then the FQN would be `a16858319_CARS`. You'll use the FQN when setting scope values for your app objects. ## App schema To create an app object, include an `app-hsmeta.json` configuration file in the `app` directory. ```shell theme={null} project-folder/ └── src/ └── app/ └── app-hsmeta.json ``` Below are the configuration options available for `app-hsmeta.json`. ```json theme={null} { "uid": "app_object_poc_app", "type": "app", "config": { "description": "An example to demonstrate how to build an app with an app object on developer projects.", "name": "my first app object app", "distribution": "marketplace", "auth": { "type": "oauth", "redirectUrls": ["http://localhost:3000/oauth-callback"], "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"], "optionalScopes": [], "conditionallyRequiredScopes": [] }, "permittedUrls": { "fetch": ["https://api.hubapi.com"], "iframe": [], "img": [] }, "support": { "supportEmail": "support@example.com", "documentationUrl": "https://example.com/docs", "supportUrl": "https://example.com/support", "supportPhone": "+18005555555" } } } ``` ### App schema \*-hsmeta.json fields

Fields marked with \* are required

| Field | Type | Description | | --------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | String | An internal unique identifier for the app. Must be globally unique within the project. Can be any string up to 64 characters. Characters can be uppercase or lowercase, and can include numbers, underscores (`_`), dashes (`-`), and periods (`.`). | | `type`\* | String | The type of component. Must match the name of the parent folder (`app`). | | `description`\* | String | A description of what the app does for the installing user. Can be any string up to 8192 characters. | | `name`\* | String | The name of the app, which will display in HubSpot. Can be any string up to 200 characters. Must not start or end with a whitespace character. | | `distribution`\* | String | The method of app distribution. Must be set to `marketplace` for the app to be eligible for HubSpot Marketplace listing. | | `auth`\* | Object | An object containing the app's authentication method details. See the [auth table](#auth-fields) for details. | | `permittedUrls` | Object | An array containing the URLs that the app is allowed to call. URLs must use the HTTPS scheme and must contain an [authority](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL#authority), followed by an optional path prefix if needed. | | `supportEmail` | String | A valid email address that users can contact for support. | | `documentationUrl` | String | The external URL that users can navigate to for supporting documentation. Must use HTTPS. | | `supportUrl` | String | The external URL that users can navigate to for additional support. Must use HTTPS. | | `supportPhone` | String | The phone number that users can contact for support. Must start with a plus sign (`+`). | ### auth fields

Fields marked with \* are required.

| Field | Type | Description | | ----------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type`\* | String | The type of authentication. Must be set to `oauth` for the app to use OAuth authentication. | | `redirectUrls`\* | Array | A list of URLs that the OAuth process is allowed to reroute back to. Each app must have at least one auth redirect URL, and it must use HTTPS. The only exception is that `http://localhost` is allowed for testing. | | `requiredScopes`\* | Array | A list of your app's required scopes. Each app must include at least one scope, and the installing user must grant these scopes to successfully install the app. [Learn more about scopes below](#scopes). | | `optionalScopes` | Array | A list of your app's optional scopes. These scopes can be excluded from the authorization during installation if the account or user installing the app doesn't have the proper permissions. In that case, the scope will not be included in the resulting refresh token or access token. [Learn more about scopes below](#scopes). | | `conditionallyRequiredScopes` | Array | A list of scopes that are required only when included in the `scope` query parameter of the install URL. [Learn more about scopes below](#scopes). | ### Scopes In the `auth` field of an app configuration file, you can specify three [types of scopes](/apps/legacy-apps/public-apps/overview#scope-types): required scopes, conditionally required scopes, and optional scopes. If you're just getting started with app objects, you should only include your app object scopes as `conditionallyRequiredScopes`. This will allow you to silo your new features to specific customers by including the app object scopes in the install URL. App object scopes use the following format: `crm.app.schemas..read` For example, for an app object with the FQN `a16858319_cars`, the `read` scope would be: `crm.app.schemas.a16858319_cars.read`. At a minimum, your app must include the above `read` scope to enable customers to access the object. It's recommended to include all app object scopes in your app, as shown below. ```json theme={null} "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": [] }, ``` For a full list of available scopes, see the [scopes reference](/apps/legacy-apps/authentication/scopes). ## Webhooks component definition To define a set of webhook subscriptions for your app, include a `webhooks` directory in the project, along with a `*-hsmeta.json` configuration file. ```shell theme={null} project-folder/ └── src/ └── app/ ├── app-hsmeta.json └── webhooks/ └── webhook-hsmeta.json ``` Below are the available configuration options for the `*-hsmeta.json` file. ```json theme={null} { "uid": "webhooks", "type": "webhooks", "config": { "settings": { "targetUrl": "https://example.com/webhook", "maxConcurrentRequests": 10 }, "subscriptions": { "crmObjects": [ { "subscriptionType": "object.creation", "objectType": "contact", "active": true }, { "subscriptionType": "object.propertyChange", "objectType": "car_app_object", "propertyName": "carProperty", "active": true } ], "legacyCrmObjects": [ { "subscriptionType": "contact.propertyChange", "propertyName": "lastname", "active": true }, { "subscriptionType": "contact.deletion", "active": true } ], "hubEvents": [ { "subscriptionType": "contact.privacyDeletion", "active": true } ] } } } ``` ### Webhook \*-hsmeta.json fields

Fields marked with \* are required.

| Field | Type | Description | | ---------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `uid`\* | String | An internal unique identifier for the webhook component. | | `type`\* | String | The type of component, which should be `webhooks` in this case. | | `settings`\* | Object | An object that specifies two fields: `targetUrl`, which is the publicly available URL for HubSpot to call where event payloads will be delivered, and `maxConcurrentRequests`, which is the upper threshold of HTTP requests that HubSpot will make in a given time frame. | | `subscriptions`\* | Object | An object that specifies the subscription types your app will subscribe to. | | `crmObjects` | Array | An array containing event subscription definitions. This is the standard array to include, and should be used for all events in the new format (`object.*`). Classic webhook subscription types should instead be included in `legacyCrmObjects` and `hubEvents` arrays, depending on the event. | | `legacyCrmObjects` | Array | An array containing classic subscription types, such as `contact.creation` and `deal.deletion`. | | `hubEvents` | Array | An array containing the classic subscription types `contact.privacyDeletion` and `conversation.*` | **Please note:** the `associationChange` event is not currently supported for app objects. For each `subscription` object, the following fields can be specified, based on the subscription definition type you're subscribed to (i.e., `crmObjects`, `legacyCrmObjects`, or `hubEvents`) or whether you're subscribing to a specific property change (e.g., `contact.propertyChange`). | Field | Type | Description | | ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subscriptionType` | String | The type of event being subscribed to. | | `objectType` | String | For subscriptions specified within the `crmObjects` array, this specifies the CRM object your app is subscribing to. For subscribing to changes to an app object, include your app object name for this field (e.g., `car_app_object`). | | `propertyName` | String | For property change subscriptions, this specifies which property will trigger the webhook event. | | `active` | Boolean | Whether webhook events will be triggered for this subscription. | ## App card schema To create an app card that appears on an app object record page, include a `cards` component directory in the project, along with a configuration file. ```shell theme={null} project-folder/ └── src/ └── app/ ├── app-hsmeta.json └── cards/ └── my-app-card-hsmeta.json └── my-app-card.jsx ``` * Make sure you've run `hs project upload` after you created your app object component and the associated configuration files. * In your `my-app-card-hsmeta.json` file, add your app object UID to the `objectTypes` array (e.g., `"app_object_uid"` in this example). Each of the available fields in the `.json` file are detailed in the [table](#app-card-*-hsmeta.json-fields) below. ```json theme={null} { "uid": "my-app-card", "type": "card", "config": { "name": "My app card", "description": "An example description of the card, which lives on contact records.", "previewImage": { "file": "./preview.png", "altText": "A short description of the preview image" }, "entrypoint": "/app/cards/MyCard.jsx", "location": "crm.record.tab", "objectTypes": ["contacts", "app_object_uid"] } } ``` * After you've saved the changes to your `example-card-hsmeta.json` file, run `hs project upload`. Cards are added automatically to the default view for app objects. If the card doesn't automatically show up, learn how to [add cards to CRM records](/apps/developer-platform/add-features/ui-extensions/extension-points/app-cards/create-an-app-card#view-the-card-in-hubspot). ### App card \*-hsmeta.json fields

Fields marked with \* are required.

| Field | Type | Description | | -------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `uid`\* | String | The card's unique identifier. This can be any string, but should meaningfully identify the card. HubSpot will identify the card by this ID so that you can change the card's title without removing historical or stateful data, such as the position on the CRM record. | | `type` | String | The type of component, which should be `card` in this case. | | `config` | Object | An object containing configuration details. | | `name`\* | String | The card's title, as displayed in HubSpot's UI. | | `description` | String | A description of the card. | | `previewImage` | Object | An object containing the `file` and `altText` fields. The `file` field is the relative path to the preview image. Valid file extensions are png, jpeg, jpg, or gif. The maximum file size is 5.0 MB. The `altText` field is a short description of the image. | | `entrypoint`\* | String | The file path of the card's front-end React code. | | `location`\* | `crm.record.tab` \| `crm.record.sidebar` \| `helpdesk.sidebar` | Where the card appears in HubSpot's UI. Learn more about [extension location](/apps/developer-platform/add-features/ui-extensions/extension-points/app-cards/reference#supported-locations). | | `objectTypes`\* | Array | The types of CRM records that the card will appear on. | ## App object associations To enable associations between your app object and other CRM objects, include an `app-object-associations` component directory in the project, along with a `*-hsmeta.json` configuration file for each record type you want to define an association for. The directory structure and example `*-hsmeta.json` file below provide an example of defining an association between an app object with a `uid` of `car-app-object` and contacts. ```shell theme={null} project-folder/ └── src/ └── app/ ├── app-hsmeta.json └── app-object-associations/ └── car-to-contact-hsmeta.json ``` Below are the available configuration options for your app object association details in the corresponding `*-hsmeta.json` file. ```json theme={null} { "uid": "car_to_contact_association", "type": "app-object-association", "config": { "firstObjectType": "car-app-object", "secondObjectType": "CONTACT", "firstToSecondBaseLimit": 5000, "secondToFirstBaseLimit": 100, "labels": [ { "name": "product_manager", "firstObjectTypeLabel": "Managed Widget", "secondObjectTypeLabel": "Product Manager", "firstToSecondLabelLimit": 1, "secondToFirstLabelLimit": 50 }, { "name": "quality_inspector", "firstObjectTypeLabel": "Inspected Widget", "secondObjectTypeLabel": "Quality Inspector" }, { "name": "technical_support", "firstObjectTypeLabel": "Supported Widget", "secondObjectTypeLabel": "Technical Support Rep", "firstToSecondLabelLimit": 3 } ] } } ``` ### Association \*-hsmeta.json fields

Fields marked with \* are required.

| Field | Type | Description | | --------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid`\* | String | An internal unique identifier for the association. Must be globally unique within the project. | | `type`\* | String | The type of component. Must match the name of the parent folder (`app-object-association`). | | `config`\* | Object | An object containing the object association configuration.

This object includes the `firstObjectType`, `secondObjectType`, `firstToSecondBaseLimit`, `secondToFirstBaseLimit`, and `labels` properties, which are defined in detail in the table rows below. | | `firstObjectType` | String | The first object type in the association. Can be an app object UID (e.g., `"car-app-object"`) or the `fullyQualifiedName` of a HubSpot-defined object (e.g., `"CONTACT"`). | | `secondObjectType` | String | The second object type in the association. Can be an app object UID (e.g., `"car-app-object"`) or the `fullyQualifiedName` of a HubSpot-defined object (e.g., `"CONTACT"`). | | `firstToSecondBaseLimit` | Number | The maximum number of `secondObjectType` records that a single `firstObjectType` record can be associated to.

The maximum value is 10,000. Note that if this property is not provided, the corresponding association limit will default to [*Many*](https://knowledge.hubspot.com/object-settings/set-limits-for-record-associations). | | `secondToFirstBaseLimit` | Number | The maximum number of `firstObjectType` records that a single `secondObjectType` record can be associated to.

The maximum value is 10,000. Note that if this property is not provided, the corresponding association limit will default to [*Many*](https://knowledge.hubspot.com/object-settings/set-limits-for-record-associations). | | `labels` | Array | An array of association labels that describe the relationships between associated records. Each label is an object with the following properties available:
  • `name`\* : Unique identifier for the first object type in this association.
  • `firstObjectTypeLabel`\* : Display label for the first object type in this association.
  • `secondObjectTypeLabel`\* : Display label for the second object type in this association.
  • `firstToSecondLabelLimit`: The maximum number of `secondObjectType` records that a single `firstObjectType` record can be associated with using this label. Cannot be greater than the base limit.

    Note that if this property is not provided, the corresponding association limit will default to [*Many*](https://knowledge.hubspot.com/object-settings/set-limits-for-record-associations).
  • `secondToFirstLabelLimit`: The maximum number of `firstObjectType` records that a single `secondObjectType` record can be associated with using this label. Cannot be greater than the base limit.

    Note that if this property is not provided, the corresponding association limit will default to [*Many*](https://knowledge.hubspot.com/object-settings/set-limits-for-record-associations).
|