API Documentation

Authentication

All API requests must include a valid API key in the Authorization header. You can create API keys from Settings > API in your dashboard.

curl -H "Authorization: Bearer fd_live_abc123..." \
  https://app.foxdrop.com/api/v1/requests

API keys use the prefix fd_live_ followed by 32 hex characters. Keep your keys secret — they grant full access to your organization's data.

Endpoints

Requests

curl -X POST https://app.foxdrop.com/api/v1/requests \
  -H "Authorization: Bearer fd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tax Documents 2025",
    "client_id": "uuid-here",
    "due_date": "2025-04-15",
    "items": [
      { "label": "W-2 Form", "required": true },
      { "label": "1099 Forms", "required": false },
      { "label": "Photo ID", "required": true }
    ]
  }'

{
  "data": {
    "id": "uuid",
    "title": "Tax Documents 2025",
    "status": "active",
    "portal_url": "https://app.foxdrop.com/p/abc123",
    "due_date": "2025-04-15",
    "created_at": "2025-03-17T12:00:00Z",
    ...
  }
}

Clients

Templates

Pagination

All list endpoints support pagination via query parameters:

{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Errors

Errors follow a consistent format with an error code and message:

{
  "error": {
    "code": "validation_error",
    "message": "Request title is required"
  }
}

Webhooks

Configure webhooks in Settings > Webhooks to receive real-time notifications when events occur. Webhooks use HTTPS POST with JSON payloads.

Event Types

Payload Format

{
  "event": "request.created",
  "payload": {
    "request_id": "uuid",
    "title": "Tax Documents 2025",
    "client_id": "uuid",
    "portal_url": "https://app.foxdrop.com/p/abc123"
  },
  "delivered_at": "2025-03-17T12:00:00Z"
}

Signature Verification

Every webhook includes an X-Foxdrop-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook secret. Verify this signature to ensure the request came from Foxdrop.

import crypto from "crypto";

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Headers

Retry Behavior

Webhooks have a 10-second timeout. If a delivery fails (non-2xx response or timeout), the failure count increments. After 10 consecutive failures, the webhook is automatically disabled. Successful deliveries reset the failure count. You can re-enable disabled webhooks from the settings page.

Rate Limits

API requests are rate-limited per API key:

• 100 requests per minute
• 1,000 requests per hour

Rate limit information is included in response headers:

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.