topic Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card in CMS Development

How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card)?

MKatewa — Wed, 09 Jul 2025 19:49:38 GMT

Hi HubSpot team and community,

I'm building a public app that uses a CRM card built with the new UI Extensions framework, and I need help enabling configuration settings per connected account (HubSpot portal).

What I want to achieve:

After a customer installs our app via the HubSpot Marketplace, they should be able to go to Connected Apps and enter 2–3 text-based configuration fields — such as a custom API endpoint URL, etc.

These configurations should be:

Saved per portal, not per user
Accessible from the UI extension React code (so we can fetch and use the config values)

Example use case:

If the customer enters a custom endpoint URL in the settings, I want to retrieve that value in the UI extension and make a request to it using hubspot.fetch().

Questions:

Is it possible to render text input fields for public apps?
How can I store these configs per portal, and how do I retrieve them later inside the extension.

Any guidance, examples, or best practices would be much appreciated!

Thanks!

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card

BrandonWoodruff — Thu, 10 Jul 2025 13:15:19 GMT

Hello!

1. Can public apps render settings fields (like text inputs) per portal?

Yes! HubSpot allows you to define custom app settings fields using the app settings schema. These settings appear in Connected Apps > Manage App, and they're stored per portal (not per user). You can use:

text
textarea
boolean
select
etc.
Example snippet from your app.json:

{ "settings": { "fields": [ { "type": "text", "name": "customApiUrl", "label": "Custom API Endpoint", "description": "Enter the URL of your custom endpoint", "required": true }, { "type": "text", "name": "accessKey", "label": "Access Key", "required": false } ] } }

These show up in HubSpot UI automatically when someone installs the app. No extra dev work needed for rendering settings.
2. How do I store config per portal?
When users fill in these fields, HubSpot automatically stores them per portal (account) as part of the app installation metadata. You don’t need a database or backend to manage this yourself.
3. How can I access these configs inside my CRM card (UI Extension)?
Use the hubspot.api.appSettings SDK method inside your React code:

import { hubspot } from '@hubspot/ui-extensions'; hubspot.api.appSettings.get() .then(settings => { const apiUrl = settings.customApiUrl; const accessKey = settings.accessKey; // Use this to make fetch requests, etc. }) .catch(error => { console.error('Failed to load app settings:', error); });
This gives you access to whatever settings the customer configured in the Connected Apps interface.

Let me know if this helps, or if you have any other questions!

✔️ Was I able to help answer your question? Help the community by marking it as a solution.

Brandon Woodruff
Senior Software Developer @ Pearagon
Still have questions? Reach out to brandon@pearagon.com

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card

MKatewa — Thu, 10 Jul 2025 17:45:22 GMT

Hi @BrandonWoodruff !!

Thanks a lot for your clear and helpful explanation — really appreciate the detailed response!

Based on your explanation, I went ahead and updated my public-app.json file to include the settings fields like this:

{ "name": "Get started with public apps", "uid": "get-started-public-app", "description": "An example how to build a public app with developer projects.", "allowedUrls": ["https://tusharbajaj.ngrok.io"], "auth": { "redirectUrls": ["http://localhost:3000/hubspot/oauth/callback"], "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"], "optionalScopes": [], "conditionallyRequiredScopes": [] }, "support": { "supportEmail": "support@example.com", "documentationUrl": "https://example.com/docs", "supportUrl": "https://example.com/support", "supportPhone": "+18005555555" }, "extensions": { "crm": { "cards": [ { "file": "./extensions/example-card.json" } ] } }, "settings": { "fields": [ { "type": "text", "name": "customApiUrl", "label": "Custom API Endpoint", "description": "Enter your external API base URL", "required": true }, { "type": "text", "name": "accessKey", "label": "Access Key", "description": "API key for authentication", "required": false } ] } }

After making the change, I did:

hs project upload
Reinstalled the public app in my Developer Test Account.

But even after reinstalling, when I go to:
Settings → Integrations → Connected Apps → Get started with public apps
,
I still don't see the settings fields I defined in the JSON. (Sharing a screenshot of what I see.)

Am I missing a step here?
Would really appreciate any pointers. Thanks again for all the help! 🙏

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card

MKatewa — Mon, 14 Jul 2025 21:57:24 GMT

Hey @BrandonWoodruff @Jaycee_Lewis @GRajput @zach_threadint @Kevin-C @Mike_Eastwood BérangèreL @deepikaverma @HubSpot_Corey @miljkovicmisa @kosalaindrasiri @JennyL

Just looping back on this in case anyone has insights 🙏

As mentioned earlier, I’ve added the settings.fields section to my public-app.json and uploaded the project using hs project upload. I’ve also reinstalled the app in my test portal.

However, when I go to:
Settings → Integrations → Connected Apps,
I still don’t see any of the custom settings fields (like customApiUrl, accessKey, etc.).

Is there anything I might be missing — like additional setup, scopes, or portal type requirements — to get the settings UI to show up?

Really appreciate any guidance you all can share. Thank you! 🙏

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card

Mike_Eastwood — Tue, 15 Jul 2025 20:50:18 GMT

Good morning from New Zealand!

Thank you @BrandonWoodruff for your solution - super helpful - implementing your idea on my new app today!

@MKatewa before I saw Brandon's post I had implemented an API call (in every card) that calls an API on my server. Using the data available in Post Parameters I can then return a useful json response with information from my database. This allows me to fully customise the Card.

Have fun

Mike

Here to learn more about HubSpot and share my HubSpot Knowledge. I'm the founder of Webalite a Gold HubSpot Partner Agency based in Wellington, New Zealand and the founder of Portal-iQ the world's first automated HubSpot Portal Audit that helps you work smarter with HubSpot.

And, I also store json in hidden properties in the CRM Object (where the Card appears) which loads really fast!

topic Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card in CMS Development

How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card)?

What I want to achieve:

Example use case:

Questions:

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card

1. Can public apps render settings fields (like text inputs) per portal?

2. How do I store config per portal?

3. How can I access these configs inside my CRM card (UI Extension)?

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card

Re: How can I store per-portal configuration (text fields) and fetch it in my UI extension (CRM card