The SourceWhale Public API allows you to programmatically interact with your SourceWhale account, adding contacts, triggering campaigns, querying statistics, and more.
📖 Interactive Documentation
Explore all endpoints and try them live at: https://sourcewhale.app/public-api/swagger
Authentication
Every API request must include your API key in the request header:
API-Key: your_api_key_here
To generate your API key:
Go to your SourceWhale dashboard and click your profile icon in the bottom left corner.
Click Admin, then Settings, then click Generate API Key.
⚠️ Admin access is required to generate an API key.
Base URL
https://sourcewhale.app/public-api
Contacts
Add Contacts: POST /v1/candidates/add
Add one or more contacts to SourceWhale. Optionally enrol them directly into a campaign.
candidates(required): Array of contact objects. Each contact can includefirstName,lastName,email,phone,socialLinks, and more.campaignId(optional): Enrol contacts into a specific campaign.projectIds(optional): Add contacts to one or more projects.sendImmediately(optional, boolean): Iftrueand acampaignIdis provided, outreach sends immediately without review.userEmail(optional, query param): Assign contacts to a specific user by email. Defaults to an admin user.
Response: Returns a url and a list of candidateIds.
Search Contacts: GET /v1/candidates/search
Look up existing contacts by a specific identifier.
key(required): Field to search by:email,phone,photo, orsocialLink.value(required): The value to search for.userEmail(optional): Restrict results to a specific user.
Response: Returns a list of matching contact objects.
Update a Contact: POST /v1/candidates/modify
Update the fields of an existing contact.
candidate(required): Object containingcandidateIdplus the fields to update.
Response: Returns "success" on completion.
Campaigns
List Campaigns: GET /v1/campaigns/list
Retrieve all live campaigns for your team.
userEmail(optional): Filter to campaigns created by a specific user.includeMetrics(optional,true/false): Include open rate, reply rate, interest rate, and booked rate.
Response: Returns a list of campaigns with campaignId and campaignName.
Projects
List Projects: GET /v1/projects/list
Retrieve all projects for your team.
userEmail(optional): Filter to projects created by a specific user.
Response: Returns a list of projects with projectId and projectName.
Statistics
Dashboard Statistics: GET /v1/statistics/dashboard
Retrieve outreach statistics for your team over a date range.
from(required): Start date inYYYY-MM-DDformat.to(required): End date inYYYY-MM-DDformat.timezone(optional): Timezone string (e.g.Europe/London). Defaults toUTC.
Response: Returns counts for sourced, sent, opened, replied, interested, and booked across the date range.
Webhooks
Subscribe to Events: POST /v1/zapier/subscribe
Register a webhook URL to receive real-time notifications when contacts are added or updated in SourceWhale.
Request body:
url(required): The webhook URL to receive event payloads.subscriptionType(required): The event type to subscribe to. Accepted values:candidateCreated: fires when a new contact is added to SourceWhale for the first time.candidateUpdated: fires when an existing contact's data is modified.
triggerKeys(optional, array,candidateUpdatedonly): Limit which fields trigger the webhook. For example,["email", "phone"]will only fire when those specific fields change. If omitted, any field change triggers the webhook.
Response: Returns an id (subscriptionId) for this webhook registration.
Example: trigger when a new contact is added:
POST /v1/zapier/subscribe{ "url": "https://your-webhook-url.com/endpoint", "subscriptionType": "candidateCreated"}
Example: trigger only when a contact's email or phone changes:
POST /v1/zapier/subscribe{ "url": "https://your-webhook-url.com/endpoint", "subscriptionType": "candidateUpdated", "triggerKeys": ["email", "phone"]}
The webhook payload will contain { "candidate": { ...contactObject } }.
Stuck or need some help? Click on the chat icon at the bottom right-hand corner to connect with our support team!