DEVELOPER DOCUMENTATION

Build on BoostServ
with the V1 API.

Create contacts, manage campaign actions, read analytics, and receive workspace events with a scoped API key.

Read the quick start Webhook guide

OVERVIEW

A workspace-scoped API

Every key belongs to one workspace. Use the deployed BoostServ app origin issued for your workspace, followed by /api/v1. BoostServ returns 404 for resources outside that workspace and never returns connection credentials, API-key secrets, or webhook signing secrets after their initial display.

Base URL

https://app.boostserv.io/api/v1

API version

v1 · additive changes

Data format

JSON · UTF-8

Availability follows your plan and key scopes. A successful saved configuration does not mean a campaign has sent, a provider accepted a message, or a webhook was delivered. Use returned status fields and async-job polling for final state.

AUTHENTICATION

Bearer key + idempotency

Send the API key in the Authorization header. Send a unique Idempotency-Key with writes; retry the same request with the same value after a timeout. Campaign writes use durable idempotency protection.

HTTP
Authorization: Bearer bsv_live_your_key
Idempotency-Key: a-client-generated-unique-value
Content-Type: application/json

Read scopes

contacts:read · analytics:read · webhooks:read

Write scopes

contacts:write · campaigns:write · webhooks:write

CONTACTS

Create and maintain customer-owned contacts

Contacts are workspace-owned. Suppressed addresses remain protected—an import or update cannot silently reactivate them.

GET/contacts

List Contacts with cursor pagination.

contacts:read
POST/contacts

Create or safely handle a duplicate Contact.

contacts:write
GET/contacts/{id}

Read one workspace Contact.

contacts:read
PATCH/contacts/{id}

Update supported Contact fields.

contacts:write
cURL · create a Contact
curl --request POST 'https://app.boostserv.io/api/v1/contacts' \
  --header 'Authorization: Bearer bsv_live_your_key' \
  --header 'Idempotency-Key: create-ada-1' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "company": "Analytical Engines",
    "on_duplicate": "skip"
  }'

CAMPAIGNS

Use revision-safe actions

Campaign actions require the current revision. A stale revision returns 409 resource_revision_conflict; refresh the resource rather than overwriting a teammate's changes.

GET/campaigns

List campaigns in the workspace.

campaigns:read
GET/campaigns/{id}

Read campaign state and revision.

campaigns:read
POST/campaigns/{id}/actions

Launch, pause, resume, or archive with revision.

campaigns:write
POST/actions

Queue an async campaign action and poll it.

campaigns:write
cURL · launch a campaign
curl --request POST 'https://app.boostserv.io/api/v1/campaigns/cmp_123/actions' \
  --header 'Authorization: Bearer bsv_live_your_key' \
  --header 'Idempotency-Key: launch-cmp-123-r4' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "launch",
    "revision": 4
  }'

ANALYTICS

Read the facts without guessing delivery

Use analytics for Contacts, accepted sends, replies, interested outcomes, bounces, and unsubscribes. delivered is intentionally null: provider acceptance is not inbox placement.

GET/analytics?from=&to=

Workspace analytics for an ISO-8601 date range.

analytics:read
GET/analytics?format=csv

Download the same permitted analytics projection as CSV.

analytics:read

ASYNC ACTIONS

Poll until the job settles

Supported long-running actions return 202 Accepted with an ID and poll_url. Poll while the job is pending or running; a settled response returns 200.

POST/actions

Create an idempotent supported async action.

action scope
GET/actions/{id}

Read job state, safe result, and errors.

same key scope

A resource export is not treated as complete merely because an action was queued. Only use a finished export artifact returned by its authorized export flow.

WEBHOOKS

Receive events safely, at least once

Configure HTTPS endpoint subscriptions from your workspace. Verify the HMAC against the exact raw request body, reject timestamps outside the replay window, and deduplicate by event id. Delivery is at least once, so consumers must be idempotent.

GET/webhook-endpoints

List configured endpoints and safe metadata.

webhooks:read
POST/webhook-endpoints

Create an HTTPS endpoint; secret is returned once.

webhooks:write
PATCH/webhook-endpoints/{id}

Update with the endpoint revision.

webhooks:write
GET/webhook-endpoints/{id}/deliveries

Inspect pending, delivered, retrying, or exhausted delivery.

webhooks:read
Webhook payload
{
  "id": "evt_123",
  "type": "contact.replied",
  "created_at": "2026-09-27T12:00:00Z",
  "workspace_id": "ws_123",
  "api_version": "v1",
  "data": {
    "object": {
      "id": "msg_123",
      "email": "ada@example.com"
    }
  }
}

Signature headers

BoostServ-Timestamp + BoostServ-Signature

Retry horizon

Up to 3 days for retryable failures

ERRORS & SAFETY

Build retries around the meaning of a response

400 invalid_request

Fix request fields; do not blindly retry.

401 / 403

Refresh or correct the API key, scope, or plan.

404 not_found

Resource is absent or outside this key's workspace.

409 conflict

Refresh state, revision, entitlement, or capacity.

Never log API keys, webhook secrets, SMTP/IMAP credentials, OAuth tokens, or raw authorization headers. Use only server-side environment variables for integration secrets.

Need integration help? Contact support