API Documentation

Learn how to integrate the Unboxed API

Authentication

All API requests require authentication using an API key. Include your API key in the x-api-key header.

curl -X POST https://api.unbox.watch/api/external/request \
  -H "x-api-key: uk_your_api_key_here" \
  -H "Content-Type": application/json" \
  -d '{
    "recipientName": "Sarah Johnson",
    "notificationEmail": "store@myshop.com",
    "notificationName": "My Shop Team",
    "message": "Thanks for your order! Share your unboxing!"
  }'

Common Use Cases

🛍️ E-commerce Orders

Recipient: Customer (package recipient)

Notification: Your business email (you receive the video)

🎁 Gift Orders (3-party)

Recipient: Gift recipient (Mom, friend, etc.)

Notification: Gift buyer email (they get to see the reaction)

📦 Subscription Boxes

Recipient: Subscriber (box recipient)

Notification: Your marketing team (collect testimonials)

Create QR Request

Generate a new QR code for recipients to record unboxing videos. The recipient opens the package and scans the QR code, while the notification recipient (business or gift sender) receives the video.

Endpoint

POST /api/external/request

Request Body

{
  // Package recipient (who receives and opens the package)
  "recipientName": "Sarah Johnson",        // Required: Recipient's name
  "recipientEmail": "sarah@example.com",   // Optional: Recipient's email

  // Notification recipient (who gets video notification)
  "notificationEmail": "store@myshop.com", // Required: Where to send video
  "notificationName": "My Shop Team",      // Required: Name for greeting

  // Optional fields
  "message": "Thanks for your order!",     // Custom message shown to recipient
  "metadata": {                            // Custom tracking data
    "orderId": "ORDER-12345",
    "sku": "WIDGET-PRO",
    "campaignId": "holiday-2025"
  }
}

Response

{
  "success": true,
  "request": {
    "id": "clxxxxx",
    "trackingCode": "ABC123XYZ",
    "status": "PENDING",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "urls": {
      "qrCode": "https://app.unbox.watch/qr/ABC123XYZ",
      "record": "https://app.unbox.watch/record/ABC123XYZ",
      "watch": "https://app.unbox.watch/watch/ABC123XYZ"
    },
    "qrCodeDataUrl": "data:image/png;base64,..."
  }
}

Example

// Node.js / Shopify Integration Example
const response = await fetch('https://api.unbox.watch/api/external/request', {
  method: 'POST',
  headers: {
    'x-api-key': 'uk_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    // Package recipient (customer)
    recipientName: order.customer.name,
    recipientEmail: order.customer.email,

    // Your business receives the video notification
    notificationEmail: 'videos@mystore.com',
    notificationName: 'My Store Team',

    // Custom message and tracking
    message: 'Thanks for your order! We'd love to see your unboxing!',
    metadata: {
      orderId: order.id,
      sku: order.items[0].sku,
      customerTier: order.customer.tier
    }
  }),
});

const data = await response.json();
// Print QR code on packing slip
printPackingSlip(order.id, data.request.qrCodeDataUrl);

Rate Limits & Quotas

Rate Limiting

Each API key has a configurable rate limit (requests per hour). Check your API key settings in the dashboard.

Usage Quotas

Your account has daily and monthly quotas. View your current usage in the dashboard.

Error Response

{
  "error": "Rate limit exceeded",
  "limit": 100,
  "current": 100,
  "resetAt": "2024-01-15T12:00:00.000Z"
}

Error Codes

400

Bad Request

Missing or invalid parameters

401

Unauthorized

Invalid or missing API key

403

Forbidden

API key inactive or account suspended

429

Too Many Requests

Rate limit or quota exceeded

500

Internal Server Error

Something went wrong on our end

Need Help?

If you have questions or need assistance integrating the API, contact our support team.

Back to Dashboard