> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getwhitewhale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> Access WhiteWhale data programmatically via REST API. Pull accounts, signals, scores, and Why Now summaries into any workflow. Full endpoint reference included.

## Overview

The WhiteWhale API gives you full programmatic access to your account data, signals, users, and Account Suggestions. Common use cases:

* Pipe WhiteWhale data into tools not covered by native integrations
* Build your own CRM integration
* Automate account uploads and status changes
* Embed WhiteWhale signal data into your own platform or internal tooling

**Base URL:** `https://app.getwhitewhale.com/v1`

**API Docs:** [https://app.getwhitewhale.com/api\_docs](https://app.getwhitewhale.com/api_docs)

***

## Authentication

Every request requires two headers:

| Header | Description |
| - | - |
| `api-key` | Your WhiteWhale API key |
| `user` | The email address of the user making the request |

```bash theme={null}
curl -H "api-key: YOUR_API_KEY" \
     -H "user: you@company.com" \
     https://app.getwhitewhale.com/v1/get_user_data
```

### Getting your API key

The API key is **shared across your whole team** — one key per WhiteWhale instance.

**1. Go to Settings**

Click **Settings** in the left nav.

**2. Scroll to API & Webhooks**

Find the **API & Webhooks** section — it manages both programmatic access and event delivery.

**3. Click Generate API Key**

Your active API key will appear. Copy it and store it securely for the team.

![Generating Api Key](https://mintcdn.com/whitewhale/P_-BreMNv7kydP3g/generating-api-key.png?fit=max\&auto=format\&n=P_-BreMNv7kydP3g\&q=85\&s=16379bfc3803c259fc597f00e1fca4ea)

> [!WARNING]
>
> Keep your API key secure and do not share it publicly or commit it to version control. Anyone with this key has full API access to your WhiteWhale instance.

***

## Rate limits & global errors

**Rate limit:** 600 requests per minute, global across all routes.

| Status code | Meaning |
| - | - |
| `401` | Authentication failed — API key missing, incorrect, or user not found |
| `404` | User or resource not found |
| `429` | Rate limit exceeded |

***

## Endpoints

### Accounts

> **GET /v1/get\_accounts — Fetch account data**
>
> Returns WhiteWhale data for your accounts. Filter by specific domains, status, or ICP. Includes signal data and account details.
>
> **Key parameters:**
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `account_filter` | array | `[]` | Filter to specific account domains |
> | `status` | string | `all` | Filter by status: `active`, `archived`, `farsight`, or `all` |
> | `signal_data` | boolean | `true` | Include signal data in response |
> | `lite` | boolean | `false` | Return lightweight response without full account data |
> | `limit` | integer | `100` | Max accounts to return |
> | `offset` | integer | `0` | Pagination offset |
> | `icp_id` | string | — | Filter to a specific ICP |
>
> **Response:** Array of `Account` objects including name, score, status, signal answers, and account details (LinkedIn URL, industry, employee count, etc.)

> **POST /v1/upload\_accounts — Add new accounts**
>
> Upload one or more accounts by domain. By default, accounts are first sent to Account Suggestions for pre-scoring before being activated.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `accounts` | array of strings | ✅ | List of account domains to upload |
> | `farsight` | boolean | — | Default `true` — sends to Account Suggestions first. Set to `false` to add directly as active. |
> | `icp` | string | — | ICP to upload accounts to. Default: `Master` |
>
> > [!NOTE]
> >
> > If `farsight: true` (default), uploaded accounts land in Account Suggestions and must be activated. If you have a webhook configured, you'll receive a pre-score payload when they're ready. If `farsight: false`, accounts are immediately active and will consume credits.

> **POST /v1/change\_accounts\_status — Archive, activate, or delete accounts**
>
> Change the status of one or more accounts. Activating accounts consumes credits.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `accounts` | array of strings | ✅ | Account domains to update |
> | `new_status` | string | ✅ | `active`, `archive`, or `delete` |
> | `icp` | string | — | ICP to apply changes to. Default: `Master` |

> **POST /v1/normalize\_accounts — Validate and normalize domains**
>
> Pass in a list of raw URLs and get back the normalized domains as WhiteWhale will store them. Useful for validating your input before uploading.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `accounts` | array of strings | ✅ | Raw account URLs to normalize |

***

### Signals

> **GET /v1/get\_signal\_templates — List signal templates**
>
> Returns the list of signal question formats the platform supports. Use these to validate signal text before adding via the API.
>
> **Response:** Array of `Template` objects with the question format, a title, whether the template is complete, and examples for templates with placeholders.
>
> ```json theme={null}
> {
>   "templates": [
>     {
>       "title": "M&A",
>       "question": "Did {account} recently acquire or merge with another company?",
>       "complete": true
>     },
>     {
>       "title": "Hiring",
>       "question": "Is {account} hiring for <<INSERT POSITION>>?",
>       "complete": false,
>       "examples": [
>         "Is {account} hiring for engineers?",
>         "Is {account} hiring for any sales positions?"
>       ]
>     }
>   ]
> }
> ```

> **POST /v1/add\_signals — Add signals to an ICP**
>
> Add one or more signals programmatically. Signals must match a template format from `/v1/get_signal_templates`, unless `ignore_templates: true` is set.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `signals` | array | ✅ | Array of signal objects (see below) |
> | `ignore_templates` | boolean | — | Default `false`. Set to `true` to add custom signals outside the template format. |
>
> **Each signal object:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `signal` | string | ✅ | The signal question text |
> | `name` | string | ✅ | A unique name for the signal within the ICP |
> | `icp` | string | ✅ | Name of the ICP to add the signal to |
> | `q_rank` | number | — | Signal rank: `0` (disqualify), `0.1` (low), `1` (normal), `6` (high) |
>
> **Signal rank behavior:**
>
> * `0` — any account matching this signal is set to an arbitrary negative score. Use to disqualify accounts.
> * `6` — Account Suggestions uses High-ranked signals to find new accounts. At least one signal of rank `6` is required for Account Suggestions to work.

> **POST /v1/delete\_signal — Remove a signal**
>
> Delete a signal from an ICP by signal ID. Retrieve signal IDs from `/v1/get_user_data`.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `signal_id` | string | ✅ | UUID of the signal to delete |

***

### Users

> **GET /v1/get\_user\_data — Get a user's data**
>
> Returns signals, ICPs, remaining credits, and active account count for the authenticated user.
>
> **Response:** `UserOverview` object with:
>
> * `icps` — list of ICP names
> * `icp_id_dict` — map of ICP name → ICP ID
> * `signals` — all signals across the user's ICPs
> * `credits_remaining` — remaining account credits
> * `active_accounts` — current active account count

> **GET /v1/get\_all\_user\_data — List all users in your instance**
>
> Returns an array of `UserOverview` objects for every user in your WhiteWhale instance. Requires admin authentication.

> **POST /v1/create\_user\_request — Create a new user**
>
> Programmatically invite a new user to your WhiteWhale instance.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `email` | string | ✅ | Email address for the new user. Stored entirely lowercase. |
> | `email_alerts` | boolean | — | Default `false`. Set to `true` to enable email alerts for this user. |
>
> **Errors:** `403` if out of user seats. `409` if a user with that email already exists.

> **POST /v1/delete\_user\_request — Delete a user**
>
> Remove a user from your instance. Requires the authenticating user to be an admin.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `email` | string | ✅ | Email of the user to delete |
>
> **Errors:** `403` if the user is not in your organization.

***

### Account Suggestions (ICP)

> **GET /v1/icp/details — Get ICP details**
>
> Returns details for one or all ICPs in your instance, including signals, Account Suggestions mode, and constraints.
>
> **Parameters:**
>
> | Parameter | Type | Description |
> | - | - | - |
> | `icp_ids` | array | Optional. ICP IDs to fetch. If omitted, returns all ICPs in your instance. |

> **POST /v1/add\_icp — Create a new ICP**
>
> Creates a new ICP as a child of your Master ICP. The new ICP inherits the Master ICP's signals.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `icp_name` | string | ✅ | Name for the new ICP. Must be unique. |
>
> **Errors:** `400` if an ICP with that name already exists.

> **POST /v1/swap\_icp — Move accounts to a different ICP**
>
> Switches one or more accounts to a different ICP.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `accounts` | array | ✅ | Account domains to move |
> | `target_icp` | string | ✅ | Name of the ICP to move them to |
>
> > [!WARNING]
> >
> > This operation can take as long as adding a new account. Plan accordingly for large batches.

> **POST /v1/delete\_icp\_request — Delete an ICP**
>
> Deletes an ICP and all its associated accounts and signals. Cannot be used to delete a Master ICP.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `icp_id` | string | ✅ | UUID of the ICP to delete |
>
> **Errors:** `400` if ICP not found for user. `403` if attempting to delete a Master ICP.

> **POST /v1/icp/farsight\_state\_switch — Enable or disable Account Suggestions**
>
> Activates or deactivates Account Suggestions for an ICP.
>
> **Body:**
>
> | Field | Type | Description |
> | - | - | - |
> | `icp_id` | string | ICP to update |
> | `state` | string | `"false"` (off), `"limited"` (only scans uploaded accounts), or `"unlimited"` (scans the full internet within your constraints) |
>
> > [!NOTE]
> >
> > At least one signal of rank `6` (High) is required for Account Suggestions to find new accounts. Account Suggestions runs automatically at 3:00 UTC daily. To trigger immediately, use `/v1/icp/run_farsight`.

> **POST /v1/icp/run\_farsight — Trigger an immediate Account Suggestions scan**
>
> Triggers an immediate Account Suggestions run for the specified ICP. Can only be called once every 2 hours.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `icp_id` | string | ✅ | ICP to run Account Suggestions for |

> **POST /v1/icp/farsight\_constraints\_change — Update Account Suggestions filters**
>
> Update the geography and industry constraints for Account Suggestions. Filters take effect immediately and will reject any queued accounts that fall outside the new parameters.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `icp_id` | string | ✅ | ICP to update |
> | `filter_list` | array | ✅ | List of countries, states, or industries to apply |
> | `inclusion_or_exclusion` | string | ✅ | `"inclusion"` or `"exclusion"` |
> | `list_type` | string | ✅ | `"country"`, `"state"`, or `"industry"` |
>
> Use ISO 3166-1 alpha-2 codes for countries, two-digit codes for US states. Retrieve valid codes from `/v1/utilities/location_codes` and valid industries from `/v1/utilities/industries`.

> **POST /v1/icp/farsight\_employee\_bounds — Set employee count range**
>
> Sets minimum and maximum employee count for Account Suggestions. Accounts outside this range are automatically rejected.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `icp_id` | string | ✅ | ICP to update |
> | `min` | integer | — | Minimum employee count. Default: `0` |
> | `max` | integer | — | Maximum employee count. Default: `0` |

***

### Webhook

> **POST /v1/set\_webhook — Register a webhook URL**
>
> Sets the webhook endpoint for your account. WhiteWhale will POST signal and account events to this URL automatically.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `webhook_url` | string | ✅ | The URL WhiteWhale should send events to |
>
> See the [Webhooks](/webhooks) page for full payload documentation.

> **POST /v1/test\_webhook — Send a test webhook payload**
>
> Sends a test payload to your registered webhook endpoint and returns the payload in the response so you can inspect it.
>
> **Body:**
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `event_type` | string | ✅ | `"account.upload"` or `"account.signal"` |
> | `spoof_payload` | boolean | — | Returns a fake payload with the correct data structure. Requires at least one signal on an account. |
> | `icp_name` | string | — | If provided, returns a real signal and account name instead of spoofed data. |
>
> > [!NOTE]
> >
> > The payload returned via this route is unsigned. The actual test payload delivered to your webhook endpoint will be signed.

***

### Utilities

> **GET /v1/utilities/location\_codes — Get valid location codes**
>
> Returns a dictionary of valid country and state codes accepted by the API. Use these when setting Account Suggestions geography constraints.

> **GET /v1/utilities/industries — Get valid industry codes**
>
> Returns all valid industry strings accepted by the API. Maps to LinkedIn's industry taxonomy.

***

## Related

> **[Webhooks](/webhooks)**
>
> Full payload reference and setup guide for WhiteWhale webhook events.

> **[Clay](/clay)**
>
> Connect WhiteWhale to Clay via webhook or CSV export.

> **[HubSpot](/hub-spot)**
>
> Native HubSpot integration for CRM sync.

> **[Salesforce](/salesforce)**
>
> Native Salesforce integration for CRM sync.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.