API Reference

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

Authentication

Every request requires two headers:

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

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.

Go to Settings

Click Settings in the left nav.

Scroll to API & Webhooks

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

Click Generate API Key

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

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`

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.

{
  "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

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)

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 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.

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.

Webhooks

Full payload reference and setup guide for WhiteWhale webhook events.

Clay

Connect WhiteWhale to Clay via webhook or CSV export.

HubSpot

Native HubSpot integration for CRM sync.

Salesforce

Native Salesforce integration for CRM sync.

Get Started

Signals

Accounts

Account Suggestions

Segments

Team Management

Integrations

How to drive deals with signals

Reference

Overview

Authentication

Getting your API key

Rate limits & global errors

Endpoints

Accounts

Signals

Users

Account Suggestions (ICP)

Webhook

Utilities

Webhooks

Clay

HubSpot

Salesforce

​Overview

​Authentication

​Getting your API key

​Rate limits & global errors

​Endpoints

​Accounts

​Signals

​Users

​Account Suggestions (ICP)

​Webhook

​Utilities

​Related

Webhooks

Clay

HubSpot

Salesforce

Overview

Authentication

Getting your API key

Rate limits & global errors

Endpoints

Accounts

Signals

Users

Account Suggestions (ICP)

Webhook

Utilities

Related