# Authentication
Source: https://docs.firmable.com/api-reference/authentication

How to authenticate your requests to Firmable's API

## Bearer Token

When requesting resources, you will need your Firmable key — you will find it in the [Dashboard](https://app.firmable.com/dashboard/profile?selected=integrations\&connection=api). Here's how to add the key to the request header using cURL:

```bash theme={null}
curl https://api.firmable.com/company/... \
  -H "Authorization: Bearer fbl_xxx"
```

Always keep your root safe and reset it if you suspect it has been compromised.


# Creating API keys
Source: https://docs.firmable.com/api-reference/creating-api-keys

General information about Firmable API

[Create your Firmable API key](https://app.firmable.com/dashboard/profile?selected=integrations\&connection=api)

<img alt="Hero Dark" />

Once you have created your API key, you can view, copy and delete and recreate a new key. You will pass this key to authenticate your requests to the Firmable API.

<img alt="Hero Dark" />


# Company Enrichment
Source: https://docs.firmable.com/api-reference/endpoint/company-get

GET /company
Returns company information

## Description

Look up a company profile by Firmable ID, LinkedIn slug, LinkedIn URL, FQDN, ABN, or website.

Use the optional `country` query param to return region-specific data. Supported country codes: `AU`, `NZ`, `SG`, `MY`, `ID`, `PH`, `HK`, `JP`, `VN`, `KR`, `TH`, `US`, `CA`. Defaults to `AU` when not provided. Returns a `400` error for unsupported country codes.


# People Enrichment
Source: https://docs.firmable.com/api-reference/endpoint/people-get

GET /people
Returns people information



# People Search
Source: https://docs.firmable.com/api-reference/endpoint/people-search

POST /people/search
Search for people by id, company id, position, seniority, and department

## Description

Search for people by company id, position, seniority, and department.

Use the `selectedCountry` field to scope results to a specific region. Supported country codes: `AU`, `NZ`, `SG`, `MY`, `ID`, `PH`, `HK`, `JP`, `VN`, `KR`, `TH`, `US`, `CA`. Defaults to `AU` when not provided.

Please pass ids for seniority and department as listed below.

## Acceptable seniority and department ids

#### Seniority:

* `1`: Board Member / Company Director
* `2`: Owner / Founder
* `3`: C-Suite / Partner
* `4`: VP/Director / Head of
* `5`: Manager
* `6`: Other
* `7`: No Data Available

#### Department:

* `1`: General Management
* `2`: Sales
* `3`: Trades
* `4`: Operations
* `5`: Engineering & Technical
* `6`: Human Resources
* `7`: Customer Service
* `8`: Medicine & Healthcare
* `9`: Research & Analysis
* `10`: Legal
* `11`: Marketing
* `12`: Education & Training
* `13`: Consulting
* `14`: Finance
* `15`: Product
* `16`: Other
* `17`: No Data Available


# HTTP Methods
Source: https://docs.firmable.com/api-reference/http-methods

General information about Firmable API

### `GET`

`GET` methods are used for reading data. Filtering, sorting, or pagination is done via query parameters.

```http theme={null}
curl "https://api.firmable.com/company?ln_slug=company_slug" \
  -H "Authorization: Bearer <FIRMABLE_API_KEY>"
```


# New to Firmable?
Source: https://docs.firmable.com/api-reference/new-to-firmable



Firmable's AI powered sales intelligence platform gives you:

<ul>
  <li>Access to over 1.5 million Australian and New Zealand B2B companies and over 10 million people.</li>
  <li>Accurate and detailed profiles with localised information, including ABNs/ NZBNs, industry segments, tech stacks, and more.</li>
  <li>Extensive mobile and email coverage.</li>
  <li>Dedicated local support in your time zone.</li>
</ul>


# Welcome
Source: https://docs.firmable.com/api-reference/overview

Firmable API is your gateway to Australia and NZ’s #1 sales intelligence platform.

[Firmable](https://firmable.com/) combines Australia and New Zealand’s B2B database with over 10 million contacts at 1.5 million companies with rich buying signals and AI agents. [Firmable](https://firmable.com/) gives you instant access to Australian and Kiwi decision makers.


# Rate Limits
Source: https://docs.firmable.com/api-reference/rate-limits

Rate limits for Firmable API

50 requests per second per API key.


# ChatGPT
Source: https://docs.firmable.com/mcp/chatgpt

Add Firmable as an app in ChatGPT

Add Firmable to ChatGPT so it can query Firmable data inside your conversations.

Firmable is a **verified ChatGPT app** (ChatGPT calls these **apps** and **plugins**
interchangeably), so the quickest way is to add it straight from the in-app store — no Client ID or
developer setup required.

## Add from the ChatGPT store

<Steps>
  <Step title="Find Firmable">
    In [ChatGPT](https://chatgpt.com), open **Apps** (also labelled **Plugins**) from the sidebar
    (under **More** if it's not pinned), or go directly to
    [**chatgpt.com/plugins?q=firmable**](https://chatgpt.com/plugins?q=firmable). Search for `firmable`,
    then click **Firmable** to open it.

    <Frame>
      <img alt="ChatGPT Plugins page with 'firmable' searched, showing the Firmable app with an add button" />
    </Frame>
  </Step>

  <Step title="Install the plugin">
    On the Firmable page, click **Install plugin**.

    <Frame>
      <img alt="Firmable plugin page in ChatGPT with the Install plugin button" />
    </Frame>
  </Step>

  <Step title="Sign in with Firmable">
    In the **Add Firmable to ChatGPT** dialog, click **Sign in with Firmable**.

    <Frame>
      <img alt="Add Firmable to ChatGPT dialog with the Sign in with Firmable button and data-sharing notice" />
    </Frame>
  </Step>

  <Step title="Follow the prompts to finish">
    Follow the remaining prompts and click **Allow** to authorize access. Once connected, enable
    **Firmable** from the **+** → **More** menu in a chat to start using it.
  </Step>
</Steps>

## Add manually (custom connector)

<Note>
  Only needed if the Firmable app isn't available in your ChatGPT plan. You'll need the **MCP URL**
  and **Client ID** — see [**URL & Client ID**](/mcp/credentials).
</Note>

<Steps>
  <Step title="Open Settings">
    In [ChatGPT](https://chatgpt.com), click your profile at the bottom of the sidebar and choose **Settings**.

    <Frame>
      <img alt="ChatGPT sidebar profile menu with the Settings option" />
    </Frame>
  </Step>

  <Step title="Open Apps → Advanced settings">
    Go to the **Apps** tab, then click **Advanced settings**.

    <Frame>
      <img alt="ChatGPT Settings Apps tab with the Advanced settings row" />
    </Frame>
  </Step>

  <Step title="Enable Developer mode and create an app">
    Turn on **Developer mode** (this is what lets you add an unverified custom connector), then click **Create app**.

    <Frame>
      <img alt="ChatGPT Advanced settings with Developer mode enabled and the Create app button" />
    </Frame>
  </Step>

  <Step title="Enter the Firmable MCP details">
    Fill in the **New App** form:

    * **Name:** anything you like — this guide uses `Firmable`
    * **Description** *(optional)*: e.g. `Firmable MCP connector`
    * **Connection:** keep **Server URL** selected and enter the MCP URL (from [**URL & Client ID**](/mcp/credentials))
    * **Authentication:** `OAuth`

    <Frame>
      <img alt="ChatGPT New App form with name, description, server URL, OAuth, and the risk acknowledgment checkbox" />
    </Frame>
  </Step>

  <Step title="Configure OAuth and create">
    Expand **Advanced OAuth settings** and set the **Registration method** to **User-Defined OAuth Client** —
    this lets you use the Firmable credentials. Enter the **Client ID** (from
    [**URL & Client ID**](/mcp/credentials); leave the secret blank unless Firmable gives you one). If Firmable asks for a redirect/callback URL, copy the **Callback URL** shown here.

    Finally, tick **I understand and want to continue** to acknowledge that custom MCP servers aren't reviewed by OpenAI, then click **Create**.

    <Frame>
      <img alt="ChatGPT New App advanced OAuth settings with the Client ID field and Callback URL" />
    </Frame>
  </Step>

  <Step title="Sign in with Firmable">
    On the prompt, click **Sign in with Firmable**.

    <Frame>
      <img alt="Add Firmable to ChatGPT prompt with a Sign in with Firmable button" />
    </Frame>
  </Step>

  <Step title="Authorize">
    Click **Allow** to grant ChatGPT access to Firmable.

    <Frame>
      <img alt="Firmable OAuth screen requesting access, with an Allow button" />
    </Frame>
  </Step>

  <Step title="Use it in a chat">
    Firmable is now connected. Choose when ChatGPT can use it, then enable **Firmable** from the **+** →
    **More** menu in a chat to start using it.

    <Frame>
      <img alt="Connected Firmable app in ChatGPT settings with its permissions and details" />
    </Frame>
  </Step>
</Steps>


# Claude (Web/Desktop)
Source: https://docs.firmable.com/mcp/claude

Add Firmable as a custom connector in Claude (Web) and Claude (Desktop)

Add the Firmable MCP server as a **custom connector** in Claude so it can query
Firmable data inside your conversations.

<Note>
  **Team and Enterprise plans:** an owner adds the connector under **Organization settings →
  Connectors → Add**, then hovers **Custom** and selects **Web**. Team members then connect to it
  from **Customize → Connectors** by clicking **Connect** on the connector labelled **Custom**.
</Note>

<Note>
  You'll need the **MCP URL** and **Client ID** — see [**URL & Client ID**](/mcp/credentials).
</Note>

## Claude (Web)

<Steps>
  <Step title="Open Customize">
    In [Claude](https://claude.ai), open the sidebar and click **Customize**.

    <Frame>
      <img alt="Claude (Web) sidebar with the Customize item highlighted" />
    </Frame>
  </Step>

  <Step title="Add a custom connector">
    Go to the **Connectors** tab, click the **+**, and choose **Add custom connector**.

    <Frame>
      <img alt="Connectors tab with the plus menu open showing Add custom connector" />
    </Frame>
  </Step>

  <Step title="Enter the Firmable MCP details">
    * **Name:** anything you like — this guide uses `Firmable`
    * **Remote MCP server URL:** the MCP URL
    * Expand **Advanced settings** and enter your **OAuth Client ID** (your Firmable Client ID).

    Find the MCP URL and Client ID on [**URL & Client ID**](/mcp/credentials). Then click **Add**.

    <Frame>
      <img alt="Add custom connector dialog with the Firmable name, MCP server URL, and OAuth Client ID filled in" />
    </Frame>
  </Step>

  <Step title="Connect">
    Firmable now appears under **Not connected**. Select it and click **Connect**.

    <Frame>
      <img alt="Firmable custom connector listed under Not connected with a Connect button" />
    </Frame>
  </Step>

  <Step title="Authorize">
    Sign in to Firmable and click **Allow** to authorize the connection.

    <Frame>
      <img alt="Firmable OAuth screen requesting access, with an Allow button" />
    </Frame>
  </Step>

  <Step title="Review tool permissions">
    Once connected, choose when Claude is allowed to use each Firmable tool, then start using it in a chat.

    <Frame>
      <img alt="Connected Firmable connector showing the list of tools and their permission settings" />
    </Frame>
  </Step>
</Steps>

## Claude (Desktop)

<Note>
  Custom connectors are brokered through your Claude account. If you **already added Firmable on the
  web**, it appears in Claude (Desktop) automatically — just open **Customize → Connectors** and click
  **Connect** (jump to step 4). If you haven't, add it from scratch below.
</Note>

<Steps>
  <Step title="Open Customize">
    In Claude (Desktop), open the sidebar and click **Customize**.

    <Frame>
      <img alt="Claude (Desktop) sidebar with the Customize item highlighted" />
    </Frame>
  </Step>

  <Step title="Add a custom connector">
    Go to the **Connectors** tab, click the **+**, and choose **Add custom connector**.

    <Frame>
      <img alt="Claude (Desktop) Connectors tab with the plus menu open showing Add custom connector" />
    </Frame>
  </Step>

  <Step title="Enter the Firmable MCP details">
    * **Name:** anything you like — this guide uses `Firmable`
    * **Remote MCP server URL:** the MCP URL
    * Expand **Advanced settings** and enter your **OAuth Client ID**.

    Find the MCP URL and Client ID on [**URL & Client ID**](/mcp/credentials). Then click **Add**.

    <Frame>
      <img alt="Add custom connector dialog in Claude (Desktop) with the Firmable details filled in" />
    </Frame>
  </Step>

  <Step title="Connect">
    Firmable appears under **Not connected**. Select it and click **Connect**.

    <Frame>
      <img alt="Firmable custom connector listed under Not connected in Claude (Desktop) with a Connect button" />
    </Frame>
  </Step>

  <Step title="Authorize">
    Claude opens your browser to authorize. Sign in to Firmable and click **Allow**.

    <Frame>
      <img alt="Firmable OAuth screen requesting access, with an Allow button" />
    </Frame>
  </Step>

  <Step title="Review tool permissions">
    Back in Claude (Desktop), Firmable shows as **Connected**. Choose when Claude is allowed to use each
    tool, then start using it in a chat.

    <Frame>
      <img alt="Connected Firmable connector in Claude (Desktop) showing the list of tools and their permission settings" />
    </Frame>
  </Step>
</Steps>


# URL & Client ID
Source: https://docs.firmable.com/mcp/credentials

Find the Firmable MCP URL and Client ID

Every MCP setup needs two values: the **MCP URL** and the **Client ID**. Here's where to find them
in the Firmable app.

<Steps>
  <Step title="Open account settings">
    In the [Firmable app](https://app.firmable.com), click the profile menu in the top-right corner and
    choose **Manage account**.

    <Frame>
      <img alt="Firmable app with the profile menu open showing Manage account" />
    </Frame>
  </Step>

  <Step title="Go to Integrations → MCP">
    In **Account settings**, open the **Integrations** tab and click the **MCP** card.

    <Frame>
      <img alt="Firmable Account settings Integrations tab with the MCP card" />
    </Frame>
  </Step>

  <Step title="Copy the Client ID and MCP URL">
    Use the copy buttons to grab the **Client ID** and **MCP URL**. Keep them handy — you'll paste
    them into Claude, ChatGPT, or your developer tool when adding the connector.

    <Frame>
      <img alt="Firmable MCP settings page showing the Client ID and MCP URL fields with copy buttons" />
    </Frame>
  </Step>
</Steps>


# IDE / Developer tools
Source: https://docs.firmable.com/mcp/developer-tools

Connect Firmable MCP to Claude Code, Codex, Cursor, VS Code, and Windsurf

Connect the Firmable MCP server to your code editor or terminal AI tools.

<Note>
  Replace `<MCP_URL>` with the MCP URL and `<CLIENT_ID>` with the Client ID — see
  [**URL & Client ID**](/mcp/credentials). Use the callback port `53612` where applicable.
</Note>

## Claude Code

Add with the CLI:

```bash theme={null}
claude mcp add --transport http \
  --client-id <CLIENT_ID> \
  --callback-port 53612 \
  firmable <MCP_URL>
```

Or add with JSON config:

```bash theme={null}
claude mcp add-json firmable \
  '{"type":"http","url":"<MCP_URL>","oauth":{"clientId":"<CLIENT_ID>","callbackPort":53612}}'
```

## Codex

Install from the **Codex desktop app** — Firmable is a verified plugin, so no MCP URL or Client ID is required, just sign in:

<Steps>
  <Step title="Find Firmable">
    In the Codex desktop app, open **Plugins** from the sidebar, search for `firmable`, then click
    **Firmable** under **Public** to open it.

    <Frame>
      <img alt="Codex Plugins page with 'firmable' searched, showing the Firmable plugin under Public" />
    </Frame>
  </Step>

  <Step title="Install the plugin">
    On the Firmable page, click **Install plugin**.

    <Frame>
      <img alt="Firmable plugin page in Codex with the Install plugin button" />
    </Frame>
  </Step>

  <Step title="Connect Firmable">
    In the **Connect Firmable** dialog, review the data-sharing notice and click **Continue to Firmable**.

    <Frame>
      <img alt="Connect Firmable dialog in Codex with the Continue to Firmable button and data-sharing notice" />
    </Frame>
  </Step>

  <Step title="Sign in to finish">
    Follow the remaining prompts to sign in with Firmable and authorize access. Once connected,
    Firmable is available to use in Codex.
  </Step>
</Steps>

Or add it with the CLI:

```bash theme={null}
codex mcp add firmable \
  --url <MCP_URL> \
  --oauth-client-id <CLIENT_ID>
codex mcp login firmable
```

## Cursor

Add to `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firmable": {
      "url": "<MCP_URL>",
      "auth": {
        "CLIENT_ID": "<CLIENT_ID>"
      }
    }
  }
}
```

## VS Code

Add to `.vscode/mcp.json` in your workspace (or your user config via **MCP: Open User Configuration**):

```json theme={null}
{
  "servers": {
    "firmable": {
      "type": "http",
      "url": "<MCP_URL>",
      "oauth": {
        "clientId": "<CLIENT_ID>"
      }
    }
  }
}
```

Or add it from the command line:

```bash theme={null}
code --add-mcp '{"name":"firmable","type":"http","url":"<MCP_URL>","oauth":{"clientId":"<CLIENT_ID>"}}'
```

VS Code opens a browser to authorize on the first connection. You can also run **MCP: Add Server** from the Command Palette for a guided setup.

## Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firmable": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<MCP_URL>",
        "53612",
        "--static-oauth-client-info",
        "{\"client_id\":\"<CLIENT_ID>\"}"
      ]
    }
  }
}
```


# Microsoft 365 Copilot
Source: https://docs.firmable.com/mcp/microsoft-copilot

Add Firmable to Microsoft Copilot Studio as a custom connector

Firmable connects to Microsoft Copilot Studio as a **Power Platform custom connector**. You create it
once in Power Apps, and it's then available to every agent in that environment.

<Note>
  **Before you start**

  * Access to [Power Apps](https://make.powerapps.com), and permission to create custom connectors
  * The Firmable **OpenAPI file**, your **Client ID** and a **Client Secret** — use **Support** at
    the top of this page and we'll send them over
</Note>

## Step 1: Create the connector

Open [**Custom connectors**](https://make.powerapps.com/customconnectors) in Power Apps.

<Info>
  **Custom connectors** isn't in the left menu by default. It's under **More** → **Discover all**, in
  the **Data** group. Pin it while you're there.
</Info>

Click **New custom connector** → **Import an OpenAPI file**.

<Frame>
  <img alt="Power Apps Custom connectors page with the New custom connector menu open and Import an OpenAPI file highlighted" />
</Frame>

Give the connector a name, then click **Import** and pick the OpenAPI file we sent you.

<Frame>
  <img alt="Import an OpenAPI file dialog with a connector name entered and the Import button for choosing the file" />
</Frame>

Click **Continue**. The server URL and connector details come from the file, so there's nothing to
fill in on the **General** page.

<Frame>
  <img alt="The General page of the newly imported connector, with the host and description filled in from the OpenAPI file" />
</Frame>

## Step 2: Set up authentication

Switch to **2. Security** using the step dropdown at the top left.

<Frame>
  <img alt="The connector step dropdown open with 2. Security highlighted" />
</Frame>

**Authentication type**, **Identity Provider**, **Authorization URL** and **Token URL** are already
filled in from the file.

<Frame>
  <img alt="Connector Security section with the Authorization URL and Token URL already filled in from the file, and Client ID, Client secret and Refresh URL still empty" />
</Frame>

Three fields are left:

| Field             | What to enter                             |
| ----------------- | ----------------------------------------- |
| **Client ID**     | From the email we sent you                |
| **Client secret** | From the email we sent you                |
| **Refresh URL**   | The same value as the **Token URL** above |

Leave **Scope** empty, then click **Create connector**.

## Step 3: Send us your Redirect URL

<Warning>
  Don't skip this step — sign-in won't work until we've allow-listed your Redirect URL.
</Warning>

Power Apps generates a **Redirect URL** that's unique to your connector, and it only appears after
you've saved for the first time.

<Steps>
  <Step title="Reopen your connector">
    Go to **Custom connectors**, find yours in the list, and click the pencil (**Edit**) icon.

    <Frame>
      <img alt="Power Apps Custom connectors list with the connector and the Edit pencil highlighted" />
    </Frame>
  </Step>

  <Step title="Copy the Redirect URL">
    Open the **Security** section. The **Redirect URL** is at the bottom — use the copy button beside
    it.

    <Frame>
      <img alt="Connector Security section with the Redirect URL field and its copy button highlighted" />
    </Frame>
  </Step>

  <Step title="Send it to us">
    Send it to us using **Support** at the top of this page, and wait for us to confirm. It's a
    quick change on our side.
  </Step>
</Steps>

## Step 4: Add it to an agent

MCP tools only run inside an agent, so this last step happens in Copilot Studio rather than Power
Apps. Open the agent you want to use Firmable in, go to **Add a tool** → **Model Context Protocol
(MCP)**, and pick your connector from the list.

<Frame>
  <img alt="The Add a tool dialog in Copilot Studio with the Model Context Protocol tab selected and the Firmable connector listed" />
</Frame>

Open the **Connection** dropdown and choose **Create new connection**.

<Frame>
  <img alt="Select a connection dialog with the Connection dropdown open, showing no connections available and the Create new connection option" />
</Frame>

Give the connection a display name if you want one, then click **Create**.

<Frame>
  <img alt="Creating a connection to use Firmable dialog with an optional display name field and the Create button" />
</Frame>

Sign in to Firmable and click **Allow**.

<Frame>
  <img alt="Firmable authorization screen listing the access being granted, with Deny and Allow buttons" />
</Frame>

Back in Copilot Studio the connection shows a green tick and **Add** becomes available. Click
**Add**.

<Frame>
  <img alt="Select a connection dialog with the Firmable connection connected and the Add button enabled" />
</Frame>

Firmable is added to the agent as a tool. From here it's ordinary Copilot Studio work — test the
agent, then publish it wherever your team needs it.

Steps 1–3 are one-off. The connector stays available under **Model Context Protocol (MCP)** for any
agent in that environment to add.


# MCP overview
Source: https://docs.firmable.com/mcp/overview

Connect Firmable to AI apps and developer tools via the Model Context Protocol

The Firmable MCP server lets AI apps and tools query Firmable data directly through the
[Model Context Protocol](https://modelcontextprotocol.io). Connect it once and your
assistant can pull company and people intelligence straight into its answers.

<Note>
  Installing the **Firmable app from the [ChatGPT store](/mcp/chatgpt#add-from-the-chatgpt-store)**
  needs no setup values — just sign in. Claude, developer tools, and adding ChatGPT manually need the
  **MCP URL** and **Client ID** — see [**URL & Client ID**](/mcp/credentials) for where to find them.
  [**Microsoft 365 Copilot**](/mcp/microsoft-copilot) is different again: we email you everything you
  need.
</Note>

## Pick your setup

<CardGroup>
  <Card title="Claude (Web/Desktop)" icon="message" href="/mcp/claude">
    Add Firmable as a custom connector in Claude (Web) and Claude (Desktop).
  </Card>

  <Card title="ChatGPT" icon="comment" href="/mcp/chatgpt">
    Add Firmable as an app in ChatGPT.
  </Card>

  <Card title="Microsoft 365 Copilot" icon="microsoft" href="/mcp/microsoft-copilot">
    Add Firmable to Microsoft Copilot Studio as a custom connector.
  </Card>

  <Card title="Developer tools" icon="terminal" href="/mcp/developer-tools">
    Cursor, Claude Code, Windsurf, and Codex via config or CLI.
  </Card>
</CardGroup>