This guide walks you through connecting your Pinpoint account to a Microsoft Copilot Studio agent so you can ask it questions about your Pinpoint data.
Before You Start: Do You Have the Right License?
This setup requires access to both Microsoft Copilot Studio and Power Apps. Here is what you need to know before proceeding.
Microsoft Copilot Studio — A standalone Copilot Studio subscription lets you build agents and connect to external data using premium connectors. You can get a standalone subscription from the Microsoft 365 admin center. The authoring license is currently free and must be assigned via the Microsoft 365 Admin Center. While authoring licenses are free, they do not include message capacity, meaning your organisation still needs a Tenant Capacity License or a pay-as-you-go model to allow your agent to respond to users once published. Microsoft LearnSchema Sauce
Power Apps — This setup uses Power Apps to create a custom connector. Custom connectors are not supported in Dataverse for Teams environments. To use custom connectors, users need appropriate Premium licenses. Fortunately, all Premium Connectors are included with the Copilot Studio authoring license, so no additional Power Apps licensing is needed specifically for using custom connectors within Copilot Studio. Microsoft LearnSchema Sauce
In short: if you have a Copilot Studio license (free or paid) and access to Power Apps through your organisation’s Microsoft 365 setup, you should be able to complete this guide. If you are unsure, check with your IT or Microsoft admin before proceeding.
What You Need Before You Start
A Pinpoint API key
Your Pinpoint subdomain (the part of your login URL before
.pinpointhq.com, e.g.acme)Access to Microsoft Copilot Studio
Access to Power Apps
The Pinpoint OpenAPI file — download it from this link (save it to your computer)
Step 1: Create a Pinpoint API Key
Log in to your Pinpoint account.
Go to API & Webhooks, under settings in the left hand navigation bar
Make sure the Pinpoint API toggle in the top-right is switched on.
Click the Create New in the top right corner and follow the on-screen instructions to create a new key.
Create the key with read-only permission to prevent the agent from accidentally changing data in your account.
Step 2: Create a Custom Connector in Power Apps
This step builds the bridge between Microsoft and Pinpoint.
Go to copilotstudio.microsoft.com and sign in.
Click Tools in the left navigation bar, then click + New tool.
In the dialog that appears, select Custom connector. This will open Power Apps.
In Power Apps, find Custom connectors in the left navigation.
Click + New custom connector and select Import an OpenAPI file from the dropdown.
In the dialog that opens, set the Connector name to
Pinpoint API.Click Import and select the
Pinpoint-API.swagger.jsonfile you downloaded earlier, then click Continue.
The setup wizard will open on the General tab with details already filled in. Leave everything as it is and click Create connector.
Power Apps will return you to the Custom connectors list where Pinpoint API should now appear.
Step 3: Add the Connector to a Copilot Studio Agent
Go back to Copilot Studio and open an existing agent, or create a new one.
In the Tools section of the agent overview, click Add tool.
In the search box, type
Pinpoint API. Select the Pinpoint ATS connector that appears.
In the tool details panel, click on Not connected and then select Create new connection from the dropdown.
A dialog will appear asking for your API key. Enter your Pinpoint API key in the
api_keyfield and click Create. The connection will now show as connected.
Click Add to add the tool to your agent.
Step 4: Set Your Pinpoint Subdomain
On the agent’s Tools tab, click on the Pinpoint ATS tool to open its settings.
Go to the Inputs section and click Add input, then select X-Original-Host.
Set the value to your Pinpoint subdomain address, for example:
acme.pinpointhq.com(replaceacmewith your own subdomain).Click Save.
Step 5: Test the Connection
In the Test your agent panel (usually on the right side of the screen), type a question such as: “Get the latest application from Pinpoint.”
The agent may show a Manage connections link the first time. Click it, find Pinpoint ATS listed as Not Connected, click Connect, then click Submit in the dialog that follows.
Go back to the agent and click Retry.
The agent should now return live data from your Pinpoint account.
If the agent keeps asking for your subdomain, you can add this line to your agent’s instructions: My Pinpoint subdomain is [your-subdomain] - use it for Pinpoint MCP execute-calls tool.
Never share your Pinpoint API key directly with the agent in chat. If you need to replace your API key, go to the Tools tab in your agent, click on the Pinpoint ATS tool, click the Connection dropdown, and select Create new connection to enter a fresh key. If you believe your key has been exposed, delete it immediately from Settings > API & Webhooks in Pinpoint and generate a new one