API and webhooks

Every account can run music outreach from its own tools. The API uses the same guarded paths as the interface, so the same entitlement, verification and sender checks apply. API access is available on the Pro Industry plan and above.

Base URL and authentication

Send your key as a bearer token on every request. Keys start with ask_live_.

Create a key in your workspace under Developers. The plaintext is shown once and stored only as a SHA-256 hash, so a lost key cannot be recovered — create a new one and revoke the old. Each key is scoped to a single account; it can never read another account's lists, campaigns or replies.

Endpoints

Examples

Set the key in your own environment; never commit it.

export PORTAL_CLIENT_API_KEY="ask_live_…"

# List your lead lists
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $PORTAL_CLIENT_API_KEY" \
  https://spotifymonthlylisteners.com/api/v1/leads

# Check verification usage
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $PORTAL_CLIENT_API_KEY" \
  https://spotifymonthlylisteners.com/api/v1/verify

Create a campaign. Save JSON to a file so newlines survive the shell.

cat > campaign.json <<'JSON'
{
  "name": "Single release outreach",
  "listIds": ["<owned-list-id>"],
  "templateId": "<owned-template-id>",
  "replyTo": "you@your-domain.com",
  "activate": false
}
JSON

curl --fail-with-body --silent --show-error \
  -X POST -H "Authorization: Bearer $PORTAL_CLIENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data @campaign.json \
  https://spotifymonthlylisteners.com/api/v1/campaigns

Every response is { "ok": true, "data": … } on success and{ "ok": false, "error": "CODE" } on failure. Verify the stored ids and counts in the response rather than assuming the write landed.

Error codes

Signed webhooks

Register an HTTPS endpoint in your workspace and choose which events you want. Each delivery is a POST with a JSON body and an HMAC-SHA256 signature over the raw request body.

Headers

Content-Type: application/json
X-Webhook-Event: campaign.launched
X-Webhook-Signature: sha256=<hex HMAC of the raw body, keyed with your signing secret>

Verify a delivery

Sign the raw body bytes before any JSON parsing or re-serialisation, and compare in constant time.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyPortalWebhook(rawBody, signature, secret) {
  if (!secret || typeof signature !== 'string') return false;
  const expected = Buffer.from(
    'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex'),
    'utf8',
  );
  const supplied = Buffer.from(signature, 'utf8');
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

Limits you should design for

• • Webhook delivery has an eight-second timeout and is best-effort. Failures are recorded against the endpoint but not retried, and there is no delivery id — deduplicate on your side and reconcile counts periodically with /stats and /campaigns.
• • A signature proves the payload came from us; it does not prevent replay. Use your own freshness check or idempotency key.
• • Reads are cached and paced against the email provider. Repeated polling of the same resource will not return faster; back off on a 429.
• • Verification is limited to 5,000 addresses per request and by your monthly allowance. Split larger batches.
• • Creating a campaign can take up to a minute because of provider pacing; a slow response is not a failure, and a timeout can follow a partial write — read the campaign back before retrying.
• • Sending volume, inbox placement and curator replies are never guaranteed by the API or by the interface.