HubSpot App Objects: When to Use Them and How to Get Approved

Hi everyone. I'm Marina. I'm the Senior Technical Program Manager on the Ecosystem Quality team here at HubSpot. And in this video, I'm going to guide you through App Objects. We will cover what they are, when they're a good fit, when they're not. I will show an example or two and demo of how to apply for access and end it with a guided checklist. So at a high level, App Objects let developers define an object schema for their app in a way that can be standardized across all HubSpot accounts that install that app. And that's a really key difference from custom objects, which many of you might be familiar with, which are account-specific. App objects currently require approval from HubSpot, so I'll show you where to find that request form and what makes a strong submission. For its good use case, and maybe ones that are not existed. So frame this as 3 common cases where app objects are appropriate. First, there's a good standard object alternative. So if the data you need to represent doesn't map cleanly to the standard objects like contacts, companies, deals, tickets, or other standard objects, then app objects may be the right answer. Second, when there's a product limitation, for example, maybe the object you want to use for the integration is only available with read-only API permissions right now, or the API has certain prerequisites that cannot be met or they're difficult to meet that are not pricing related. As an example, maybe you want to use the Payments API to bring in payments data from another platform. But according to the documentation, as of today, the, one of the limitations is that to use the Payments API, the account must be set up to collect payments through their HubSpot Payments or Stripe payment processing. And maybe some of your customers don't have this set up, and that's not what this object really represents. In that case, App Objects can help. And the third good use case is when there is a major product gap. So an example here would be when there's a related feature technically supports an extension through API, but that data still won't be visible to customers in the record experience. So let's say activities may support custom properties through the Properties API, but those properties are not visible to customers on the meeting record. In cases like that, App Objects once again can help. Now there are, for those that are not a good fit, there are some clear cases where App Objects are not the right solution. One, when there is a need to store sensitive data. App Objects currently do not support sensitive data, so they should not be used here. We recommend storing sensitive data either in standard objects that support the sensitive data like contacts, tickets, companies, and a few other ones, or custom objects. The second reason, when there is a need for account-specific customization. So if you have customers who need their own object design, name, or schema definitions, and the customers are very particular about this, then again, F objects may not be a good fit, and we recommend using custom objects instead. The third reason is that internal use case. So if you're building for your own internal need for private app, or if you simply wanna test the functionality, then that's not an eligible app object request based on our current guidelines. And then for the fourth case is for that moment in time data. If what you're storing is really an event or action that happen at a point in time and it's meant to be mutable, like an SMS message being sent or transaction being refunded, then we recommend using App Events instead. So let's make this concrete with one or two examples. So in this example, let's say you're building an app where you wanna track time spent working on tickets. So you have different contacts may work on the same ticket over the course of multiple weeks, or maybe just one week. This is a great fit for an app object, let's say called Time Log, because you can't store this information on a standard object. You want to be able to update this information and do some calculations within the object itself, and app events won't work here as well. So in this case, it is a good use case. And here we have an entity relationship diagram and a schema. Both are going to be required. To submit the request showing that association and cardinality of the one-to-many relationships between ticket and the time log app object. So in this example, we have location app object. So let's say you are building an app where you want to, uh, help companies to manage multiple physical locations. Take HubSpot as example. HubSpot has a headquarters in Cambridge, Massachusetts, but also has an office in Ireland and Singapore and Colombia and many other countries. Each of those locations has their own properties like address, hours of operation, phone number, number of floors, the building type, facilities that are available to the employees. Again, this information can't necessarily be stored on a object if there are just so many properties and so many locations for one company. So then we want to separate that information out. Again, we have an entity relationship diagram showing that one-to-many relationship between the company and location with the schema as well. So let's say you've identified a good use case. So the next step is to submit the form. The HubSpot official documentation, we have overview of app objects. Okay, so the overview of App Objects has the form and also this callout that, again, the feature requires approval. So let's navigate to the form and I'll guide you through the form and exactly what information is needed and how to complete it in such a way that it makes for the team really fast and easy to, uh, review. So we clicked on that in Form app. And immediately we are able to select the account. We'll navigate to request access to advanced features. This also is available within the overview of the development platform within your account. Let's say request access and we'll immediately see that form. So the form has a quick introduction to what app objects are, who should request it, and what is needed. There's a quick callout of currently We typically respond within 10 business days. That is our SLA. This is to first response, not necessarily we guarantee that you will get access or we'll come to a decision within 10 business days. We also require one form per app object submission. That means if you are a developer and you want to request, say, 5 app objects, this form should be submitted 5 times, once for each object. Let's navigate to what is needed to get started. One, we'll need two documents. So the first document is the entity relationship diagram, the ERD. So this is a concise view of how your app models and extends data. And as mentioned here, this should represent your entire app data model. So all requested app objects, all standard objects that you're integrating with, you're submitting multiple app objects request, they should all be within this one ERD and submit the same file multiple times. It should include, again, your app objects, the standard objects, the associations, and the cardinality. So seeing that cardinality, if it's, you know, one-to-one, one-to-many, many-to-many, significantly helps the team understand the relationship and help more or less predict the volume of records needed. The second document that we request can be either text or a spreadsheet, and that is the schema. So you want to know, as shown in the previous example, the properties, all of the properties, their descriptions, their property types, and the sample data. So that helps the team understand how many properties you plan on storing within a specific object and also can provide recommendations if maybe some properties need to be their own app object or, uh, maybe an app event or can be stored elsewhere. For the property types. I actually highly recommend reviewing this documentation, that is the Understand Property Field Types in HubSpot Knowledge Base, to see what types of property types available within HubSpot. Now let's complete the form. So we'll say my name, Marina Lupin here, the email. I'll just provide some sample data. I won't be completing or submitting this form. There's some additional validation in place. And we have company name Acme, right? The next is the app information. So here you want the account hub ID. So this is the production account where you will build and define all of your apps, including your non-production apps and your production apps. Only one account will be granted access and test accounts will not be accepted. So please only provide one account and request for additional accounts also will not be approved. Just submit sample data here. Your production and non-production app IDs. So we recommend having different environments so you can first test in your non-production ID, FID, and then release the, your tested and implemented features in your production app. App status. So this is whether it's new or listed. So listed in the new marketplace or net new. This helps the team determine and just get additional information, especially if it's listed so we can learn more about your app from the listing. But let's say here it's a net new app. The next is the app name, and this is directly just pulled from the branding guidelines. Highly recommend reviewing this, especially as you're preparing to list your app in the marketplace if you have not already. And let's call this Office Spaces. For the proposed app prefix, which is next. So here an app prefix is a string that precedes the singular or plural name of the object in HubSpot's UI to help differentiate it from other objects. There's an example. So if you have prefix room, app object car, in the UI it will display room car. This way, if another developer builds another car object, that prefix is going to be different and the customer will now Room car belongs to Room app, different car objects can belong to that other app. And we have the prefix must be same or similar to your app name. Again, to help the customers identify that this is your app, we'll just copy Office Spaces and let that be it. Then it must not lead with lowercase, check. Must not use all capital letters unless it's an acronym. Must not imitate or abbreviate any HubSpot brands or names. So this is following the branding guidelines. And then it must include your company name if building a connector app for other trademarked software. So example, Acme QuickBooks connector. So here, let's say if you're a first-party or second-party developer, means you are employed by the software company that integrates its own product with HubSpot. Let's say you are employee of QuickBooks as an example, and you're building a connector and you can say QuickBooks Connector or QuickBooks. But let's say if I'm an independent contractor or a company that I work for, a company that specializes in integrating various platforms, but I'm not associated or affiliated in this example with QuickBooks, then I'd be considered a third-party developer. So I would want to include the company name just to help further differentiate the trademark software there. But in this case, let's say I work for Office Spaces, I own Office Spaces, and this is my app. So we'll continue. For app purpose, so we want to provide a brief description of the functionality of the app as it stands today. And this is key. Assume that the reader is not aware of the purpose of your app and what your company does. There are many platforms and companies out there, and having that purpose and description really helps the team. Acme Office Spaces helps companies track multiple office locations for various internal purposes and automations for rolling out emails about office announcements. Next page, we have now the app object information. So we need the proposed app object name. So this is the name that is internal name used to identify the object type in the system. This means that whatever this object name, this will be also part of the scope. When you request the scope permissions from customers, this will be the name that will be present. And then you will separately define the singular and plural form visible to the customers in the UI. So let's go with our location example and the requirements. This must be different from your office app name. That way there's just no duplication. So let's say if I wanted office space, this is instead of office spaces, office spaces. So here we have location, so we'll have it be separate. It must be uppercase, uh, with underscores and singular format, and it must be in English. If you want to later change the language, you can edit that singular and plural form. So we'll use the Location app object here. Then we have the object type use case. So we want to describe the object you would like to include in the app and the role it plays in the data model. A brief description of any existing HubSpot-defined objects. These are the standard objects that have been considered, um, using instead, as well as app events. This to help team, uh, understand the rationale for the app object and a concrete example. So here, say, location describes the physical building location of a company office. It will store information about an office to help companies track their locations. Say I considered using company records, but some companies have a large number of locations and plan to store 20 properties. You know, I could expand on this. You know, let's say my largest customer has 100 offices and I want to store 20 properties. That means, you know, 2,000 properties. That simply cannot be done since an object can have up to 1,000 properties. So it's best to use an app object. Here it would be used by Vasilisa. Facilities, let's say team to send out emails about operating hours and emails about the available facilities to employees. All right. Then we have the proposed ERD. So we'll add that ERD, the same one that was shown in the slides, the proposed schema. And then I will add any features that I would want to use with this app object. So let's say app cards and reporting and workflows. And the last two questions we have, it's just very open-ended, optional. Any additional questions or important details you'd like us to know. And then the record limit agreement. So currently there's only a 3 million App Object record limit per portal for its lifetime. By saying agree means you agree to the record limit. If you're concerned then that you might go over, this is probably a good time to raise this to the team and then click submit. Now let's say I want to create an additional app object. Then after clicking submit, I would again complete another form. I might submit that same exact ERD if it already has all of my app objects and the new schema, the new object use case as well. And now I will share the self-guided checklist. So for the self-guided checklist and the key takeaways here. So you want to build an app object, want to make sure you're building a public app. So this is not a private app. You want to be using projects in the development platform. So legacy apps will not be accepted here. Verify that it is a good use case. So please do due diligence and research and really investigate if there are standard objects that exist that can be leveraged instead. Again, if you have multiple requests, submit one form per app object request. The team may not review your request until that is completed. And again, this helps with tracking and just knowing that which objects are requested and what the requests are for specifically. And then for the form, include the purpose. So this is app purpose, the use case. So should both should be very clearly defined. The app prefix, keeping in mind whether you're employed by the company that you're building for and integrating, or if you are that third-party developer, you're helping to integrate two platforms together. The app object name should be finalized as well. And we've— I recommend also avoiding any of the standard HubSpot-defined objects as well, if any of them do mimic and have those product limitations or gaps. A complete ERD, the Entity Relationship Diagram, should be complete and include all standard and app objects with the associations and the cardinality. Finally, the schema. If you have a strong use case, certainly submit the form and the team would be happy to review and provide feedback. Thanks for watching, and I hope this helps you decide faster whether app objects are the right path and how to submit the request that's ready for review.