API Reference

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer bulk_ak_your_api_key_here

Create API keys in the dashboard. Keys are shown once on creation — store them securely. All keys are prefixed with bulk_ak_ and are SHA-256 hashed before storage.

Response Format

All responses follow a consistent envelope:

{
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "...",
    "retryAfter": "2026-..."
  }
}

Plan Limits

BulkAPIs uses an annual membership model. Each plan includes a yearly API call quota. Social features (DMs, posts, account management) require a Social Accounts add-on ($50/mo per 50 accounts).

When you exceed your plan limit, API calls return a 403 with code API_CALLS_EXCEEDED. Upgrade your membership to increase your quota.

Quick Start

curl -X POST https://bulkapis.com/api/v1/dm/send \
  -H "Authorization: Bearer bulk_ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "your_account_id",
    "recipientUserId": "target_x_user_id",
    "text": "Hello from BulkAPIs!"
  }'

Endpoints

POST /api/v1/dm/send

Send a DM to any X/Twitter user. This is the core feature — most providers cannot initiate new DM conversations. Requires Social Accounts add-on.

Request Body

{
  "accountId": "string",          // Your connected account ID
  "recipientUserId": "string",    // X user ID of the recipient
  "text": "string"                // Message content (max 10,000 chars)
}

Response (202 Accepted)

{
  "success": true,
  "data": {
    "jobId": "abc123",
    "status": "queued",
    "message": "DM queued for delivery"
  }
}

DMs are processed asynchronously via a job queue. Set up a webhook for dm.sent and dm.failed events to track delivery status.

POST /api/v1/posts

Create a new post (tweet) on X/Twitter via a connected account. Requires Social Accounts add-on.

Request Body

{
  "accountId": "string",      // Your connected account ID
  "text": "string"            // Post content (max 280 chars for tweets)
}

Response (202 Accepted)

{
  "success": true,
  "data": {
    "jobId": "def456",
    "status": "queued",
    "message": "Post queued for publishing"
  }
}

Example

curl -X POST https://bulkapis.com/api/v1/posts \
  -H "Authorization: Bearer bulk_ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_xxx",
    "text": "Hello world from BulkAPIs! 🚀"
  }'

GET /api/v1/accounts

List all connected social media accounts for the authenticated user.

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "acc_xxx",
      "platform": "x",
      "platformUserId": "1234567890",
      "username": "johndoe",
      "displayName": "John Doe",
      "isActive": true,
      "needsReauth": false,
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ]
}

Example

curl https://bulkapis.com/api/v1/accounts \
  -H "Authorization: Bearer bulk_ak_your_key"

POST /api/v1/webhooks

Create a new webhook endpoint to receive real-time event notifications.

Request Body

{
  "name": "string",             // Descriptive name
  "url": "string",              // HTTPS endpoint URL
  "secret": "string",           // (optional) HMAC-SHA256 signing secret
  "events": ["string"],         // Array of event types to subscribe to
  "isActive": true              // (optional) defaults to true
}

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "wh_xxx",
    "name": "Production Webhook",
    "url": "https://example.com/webhooks",
    "events": ["dm.received", "dm.sent"],
    "isActive": true,
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Example

curl -X POST https://bulkapis.com/api/v1/webhooks \
  -H "Authorization: Bearer bulk_ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://example.com/webhooks",
    "secret": "whsec_my_secret",
    "events": ["dm.received", "dm.sent", "dm.failed"]
  }'

Webhook Events

Configure webhooks to receive real-time event notifications. All payloads are signed with HMAC-SHA256 using your webhook secret.

Signature Verification

// Verify the X-BulkAPIs-Signature header
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');
const isValid = signature === request.headers['x-bulkapis-signature'];

Delivery

Webhooks are delivered with automatic retries (up to 5 attempts) using exponential backoff. Failed deliveries after all retries are moved to a dead letter queue. Expect delivery within seconds of the event.

Payload Format

{
  "event": "dm.received",
  "timestamp": "2026-02-22T01:00:00Z",
  "data": {
    "accountId": "acc_xxx",
    "conversationId": "1234-5678",
    "messageId": "msg_xxx",
    "senderId": "9876543210",
    "senderUsername": "johndoe",
    "text": "Hey, I commented on your post!",
    "createdAt": "2026-02-22T01:00:00Z"
  }
}

Headers Sent

Content-Type: application/json
X-BulkAPIs-Signature: <hmac-sha256-hex>
X-BulkAPIs-Event: dm.received
X-BulkAPIs-Delivery-Id: <uuid>
X-BulkAPIs-Timestamp: <iso-8601>

Rate Limits

Rate limits are applied per connected account for platform-specific actions and per API key for general requests. Rate-limited responses include a Retry-After header.

Error Codes