CloutAPI Documentation

CloutAPI provides a RESTful interface for operators building social growth platforms. This documentation covers authentication, order management, and webhook integration.

⚠️ Service Abstraction Notice

Service IDs represent abstract categories. Fulfillment sources may change while maintaining consistent APIs. Delivery speed, refill behavior, and outcomes may vary. CloutAPI does not guarantee delivery or specific results.

Base URL

https://api.clout.llc/v1

Quick Start

curl https://api.clout.llc/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your_unique_key" \
  -d '{"service":"ig_followers_hq","target":"@username","quantity":1000}'

Always include an Idempotency-Key header for POST requests to prevent duplicate orders on retry.

Authentication

Authenticate via the Authorization header using Bearer token format:

Authorization: Bearer clout_live_sk_xxxxxxxxxxxxx

💡 Test vs Live Keys

Test keys (clout_test_sk_) return simulated responses without placing real orders or deducting balance. Live keys (clout_live_sk_) place actual orders and deduct from your account balance. Test mode webhooks are still delivered for integration testing.

Service Abstraction

⚠️ Critical: Service IDs are Abstract Identifiers

Service IDs (e.g., ig_followers_hq) represent abstract service categories, not specific fulfillment sources. Clout may route orders to different upstream providers while maintaining the same service ID and response format.

What This Means

Aspect	May Vary	Consistent
Fulfillment source	Yes — routing changes based on provider health	—
Delivery speed	Yes — 1-72 hours typical range	—
Refill behavior	Yes — depends on provider	—
API response format	—	Yes — always consistent
Webhook events	—	Yes — always delivered
Order ID format	—	Yes — always `ord_` prefix
Billing/ledger	—	Yes — always accurate

Implications for Your Integration

Do not rely on specific delivery times or provider behavior. Build your integration to handle:

Variable delivery windows (check status via webhooks or polling)
Partial completions (order.partial status)
Order failures (order.failed status with refund)

No Guarantees

CloutAPI does not guarantee delivery speed, completion rates, or specific outcomes. Service quality depends on upstream providers which Clout monitors but does not control.

Idempotency

To safely retry requests without risk of duplicate orders, include an Idempotency-Key header:

Idempotency-Key: ord_unique_key_12345

Keys are stored for 24 hours. If you retry a request with the same key, you'll receive the original response.

Best Practices

Scenario	Recommendation
Network timeout	Retry with same idempotency key
5xx errors	Safe to retry with exponential backoff
4xx errors	Do not retry (client error)

Rate Limits

API requests are rate limited per API key and per IP address.

Tier	Requests/min	Burst
Starter	60	10
Growth	300	50
Enterprise	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705071660

Errors

Standard HTTP codes indicate success or failure. All errors include a structured response body with a request_id for support reference.

Code	Description	Retryable
`200`	Success	—
`400`	Bad Request — Invalid parameters	No
`401`	Unauthorized — Invalid or missing API key	No
`402`	Payment Required — Insufficient balance	No (add funds first)
`404`	Not Found — Resource doesn't exist	No
`409`	Conflict — Idempotency key already used with different params	No (use new key)
`422`	Unprocessable — Valid syntax but cannot process (e.g., invalid target)	No
`429`	Too Many Requests — Rate limit exceeded	Yes (after backoff)
`500`	Server Error — Internal error	Yes (with idempotency key)
`502`	Bad Gateway — Provider unreachable	Yes (with idempotency key)
`503`	Service Unavailable — Temporarily overloaded	Yes (after backoff)

Error Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "message": "Insufficient balance for this order. Required: $24.99, Available: $10.00",
    "param": null,
    "request_id": "req_1a2b3c4d5e",
    "retryable": false
  }
}

Error Types

Type	Retryable	Description	Action
`invalid_request_error`	No	Invalid parameters or malformed request	Fix request and retry
`authentication_error`	No	Invalid API key or permissions	Check API key
`rate_limit_error`	Yes	Too many requests	Wait for X-RateLimit-Reset
`api_error`	Yes	Server-side issue	Retry with same idempotency key
`provider_error`	Yes	Upstream provider issue	Retry with same idempotency key

Always Include request_id in Support Requests

When contacting support about an error, include the request_id from the error response. This allows us to trace the exact request in our logs.

Webhooks

Receive real-time order status updates. Configure your endpoint URL in the Dashboard.

Events

Event	Description	Final State
`order.created`	Order accepted and queued	No
`order.processing`	Order sent to provider	No
`order.completed`	Order fulfilled (check `delivered` count)	Yes
`order.partial`	Partially fulfilled (check `delivered` vs `quantity`)	Yes
`order.failed`	Order failed (balance refunded)	Yes

⚠️ Always Verify Delivered Count

Even for order.completed events, always check the delivered field in the webhook payload. The delivered count may differ from the requested quantity.

Webhook Signatures

All webhooks include a signature header for verification:

Clout-Signature: t=1705071600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Verify the signature using HMAC-SHA256 with your webhook secret:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const [t, v1] = signature.split(',').map(p => p.split('=')[1]);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(t + '.' + payload)
    .digest('hex');
  return v1 === expected;
}

Retry Policy

Failed webhook deliveries are retried with exponential backoff: 1min, 5min, 30min, 2hr, 24hr. After 5 failures, the webhook is disabled and you'll receive an email notification.

Create Order

POST/v1/orders

Creates a new order. Always include an Idempotency-Key header to prevent duplicate orders on retry.

Request Headers

Header	Description
`Authorization`required	Bearer token: `Bearer clout_live_sk_xxx`
`Content-Type`required	`application/json`
`Idempotency-Key`recommended	Unique key for this request (max 255 chars)

Request Body

Parameter	Type	Description
servicerequired	string	Service ID (e.g., `ig_followers_hq`)
targetrequired	string	Target URL or username
quantityrequired	integer	Number of units (within service min/max)
metadataoptional	object	Custom key-value data (max 10 keys)

Response

{
  "id": "ord_7x9K2mN4pQ8r",
  "object": "order",
  "status": "pending",
  "service": "ig_followers_hq",
  "target": "@techstartup",
  "quantity": 1000,
  "start_count": 15420,
  "delivered": 0,
  "cost": 24.99,
  "currency": "usd",
  "created_at": "2025-01-12T15:00:00Z"
}

Response Fields

Field	Type	Description
`id`	string	Unique order identifier
`status`	string	One of: `pending`, `processing`, `completed`, `partial`, `failed`, `canceled`
`start_count`	integer\|null	Target's count at order creation (if available)
`delivered`	integer	Units delivered so far
`cost`	number	Amount charged to your balance

⚠️ Service Abstraction Reminder

The same service ID may be fulfilled by different providers. Delivery speed and behavior may vary. Do not rely on specific timing.

Get Order

GET/v1/orders/:id

Retrieves order details.

List Orders

GET/v1/orders

Returns paginated orders, most recent first.

Query Parameters

Parameter	Description
limitoptional	Results per page (1-100)
statusoptional	Filter by status
serviceoptional	Filter by service

Cancel Order

POST/v1/orders/:id/cancel

Cancels a pending order. Only orders with status: pending can be cancelled. Orders that have started processing cannot be cancelled.

Response

{
  "id": "ord_7x9K2mN4pQ8r",
  "status": "canceled",
  "refunded": true,
  "refund_amount": 24.99
}

Errors

Code	Message	Reason
`400`	Order cannot be canceled	Order is not in `pending` status
`404`	Order not found	Invalid order ID or not your order

List Services

GET/v1/services

Returns available services with current pricing.

Response

{
  "data": [{
    "id": "ig_followers_hq",
    "name": "Instagram Followers - High Quality",
    "platform": "instagram",
    "type": "followers",
    "cost_per_1k": 24.99,
    "min_quantity": 100,
    "max_quantity": 100000,
    "refill_days": 30,
    "status": "active"
  }]
}

Response Fields

Field	Type	Description
`id`	string	Service ID to use in order creation
`name`	string	Human-readable description (for reference only)
`cost_per_1k`	number	Your cost per 1,000 units
`refill_days`	integer	Refill window in days (0 = no refill)
`status`	string	`active` or `degraded`

⚠️ Service IDs are Abstract

The name field is for reference only. Service characteristics may vary as fulfillment is routed across multiple providers. Do not display service names to end users as product guarantees.

Get Balance

GET/v1/balance

Returns your account balance calculated from the immutable ledger.

{
  "available": 1247.50,
  "pending": 124.00,
  "currency": "usd"
}

Response Fields

Field	Description
`available`	Balance available for new orders
`pending`	Balance reserved for processing orders

Balance is calculated in real-time from ledger entries. Use GET /v1/ledger (coming soon) to view transaction history.