ai-shelf for HubSpot: setup guide

1. Overview

The ai-shelf app for HubSpot puts your brand's AI visibility on the Company record. ai-shelf measures how often and how well AI assistants such as Claude, ChatGPT and Gemini name your brand when customers ask them real questions, how you rank against competitors and which fixes would win you more of those answers. The app shows those results to your sales, marketing and account teams where they already work.

On a Company whose domain matches your brand's website, the ai-shelf card shows:

• the AI visibility score (0 to 100) of the latest run, with the change against the run before;
• your rank against the competitors in your market panel, and the brand AI recommends most;
• the score trend across your runs;
• the top 3 fixes from your latest report, each based on the answers AI gave;
• a Request a new run button and a link to the full report in ai-shelf.

Use cases: account and brand managers check AI visibility before a client meeting; marketing teams see the next fixes without opening another tool; sales teams ask for a new run from the record when a campaign starts.

2. Before you start

• An ai-shelf account with at least one brand. Accounts are opened by Markapp; book a demo or write to adtech@markappmedia.site.
• The admin role in your ai-shelf account (the person Markapp invited first has it).
• A HubSpot account where you are a Super Admin or have the App Marketplace Access permission.
• Your brand's website on the brand in ai-shelf (Markapp sets it when the brand is added). The card uses it to match HubSpot companies.
• Pricing is per run: USD 1,000 for the first run and USD 500 for each further run, for 2 AI assistants. There is no subscription and the HubSpot app costs nothing extra.

3. Install the app and connect your HubSpot account

1. Open aishelf.tech/integrations/hubspot/install, or click Install on the ai-shelf listing in the HubSpot App Marketplace.
2. Sign in to ai-shelf with your admin account if you are not signed in yet.
3. HubSpot asks you to choose the HubSpot account to connect. Choose it and click Choose account.
4. HubSpot shows the access ai-shelf asks for. Review it and click Connect app.
5. You return to aishelf.tech, which confirms HubSpot is connected and names the HubSpot account and your ai-shelf account.

Access requested. One scope only: crm.objects.companies.read, to read the Company domain name and Website URL of the company the card is shown on. ai-shelf never writes to HubSpot and does not read contacts, deals, tickets, emails or any other object.

Each HubSpot account connects to one ai-shelf account. If your HubSpot account is already connected to another ai-shelf account, ai-shelf says so and Markapp helps you move it.

4. Configure the app

There is nothing to map and no sync to turn on. The data flows one way, from ai-shelf into the card, and only while someone has a Company record open.

1. In HubSpot, open any Company record.
2. If the ai-shelf card is not on the page yet, add it once for everyone: click the settings icon, go to Data Management > Objects > Companies > Record Customization, open the Default view, click the add icon in the middle column, open the Card library, find ai-shelf AI visibility, click Add card and then Save and exit. Super Admins and users with the Customize record page layout permission can do this. HubSpot's guide: customize the middle column of records.
3. Check the match: the card looks for the brand in your ai-shelf account whose website has the same domain as the company (example.com, www.example.com and shop.example.com all match example.com). To match another domain, ask Markapp at adtech@markappmedia.site to update the brand's website.

Existing and new companies are both covered at once: the card reads the record when it opens, so there is no first sync to wait for.

5. Use the app

Automatic. Each time a Company record opens, the card loads the latest ready ai-shelf results for the matching brand. When Markapp finishes a new run, the card shows it the next time the record opens. A company with no matching brand shows the brands in your account; a HubSpot account that is not connected shows a Connect ai-shelf link.

By hand. Request a new run sends a request to your Markapp contact, with your name, the brand and the HubSpot account it came from. It is a request, not an order: no run starts and nothing is charged until Markapp confirms scope and price with you. Requests also appear in ai-shelf under Requests. Open the full report opens the brand in ai-shelf, where you sign in as usual.

6. Disconnect your HubSpot account

1. Open aishelf.tech/integrations/hubspot/manage and sign in with your ai-shelf admin account.
2. Next to the HubSpot account, click Disconnect and confirm.

What happens to your data. ai-shelf deletes the HubSpot access tokens at once and the card shows Connect ai-shelf instead of results. Nothing changes in HubSpot, because ai-shelf never writes there. Your ai-shelf results, reports and requests stay in ai-shelf. ai-shelf keeps a short record of the connection (HubSpot account ID and domain, who connected and disconnected it, and when) for security and support; ask adtech@markappmedia.site to delete it.

7. Uninstall the app

1. In HubSpot, click the settings icon in the top navigation bar.
2. In the left sidebar, go to Integrations > Connected Apps.
3. Next to ai-shelf, click Actions > Uninstall, type uninstall and click Uninstall.

HubSpot's guide: uninstall an app.

What happens to your data. The card disappears from your records. HubSpot revokes ai-shelf's access; the next time ai-shelf tries to use it, it marks the connection as revoked and deletes the tokens. Your HubSpot data is unchanged and your ai-shelf results stay in ai-shelf. To connect again later, install the app again.

8. Data, privacy and accessibility

• What ai-shelf receives from HubSpot: the HubSpot account ID and domain, the email of the person who connected it, OAuth tokens, and, for the record the card is shown on, its domain and website and the viewing user's HubSpot user ID and email (HubSpot adds these to every card request).
• Tokens are stored encrypted. The company domain is used to pick the brand and is not stored. A user email is stored only on a run request, so Markapp knows who asked.
• Every card request is signed by HubSpot and checked by ai-shelf before any data is sent back. A HubSpot account only ever sees the brands of the ai-shelf account it is connected to.
• No personal data is sold or used for advertising. Rights under the GDPR, retention and the controller's details are in the Privacy policy; use of the service is under the Terms of service.
• The card is built from HubSpot's own UI components, so it follows HubSpot's keyboard, screen reader and colour contrast support. This guide uses plain HTML headings, lists and text alternatives for every image.

9. Support

Write to adtech@markappmedia.site with your HubSpot account ID (in HubSpot: your account name, top right) and what you see. We reply on business days. Your Markapp contact can also help in the meetings you already have.