UGCDocumentation

Server-Side API Overview

Real server-to-server endpoints for campaigns and payment links

Updated August 28, 2026
POST/automation/webhooks/subscribe
Required

Real server-to-server endpoints for campaigns and payment links

Rate Limit

This endpoint is limited to 100 requests per 1 minute per API key.

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining

Interactive API PlaygroundTest this endpoint directly from your browser

Credentials

Your API key is never stored and only used for this request

curl -X POST https://api.ugc.africa/automation/webhooks/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY"
Coming soon

SDK examples (coming soon)

JavaScript
// Official Node SDK - coming soon. Use REST (see Getting Started) or fetch() examples.
// Planned: npm install @UGC/node

Official @UGC/* client libraries are on the roadmap. Integrate with the REST API and webhooks today. SDK pages · Email notify

Success

JSON
{
  "id": "..."
}
curl
curl -X POST https://api.ugc.africa/automation/webhooks/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Base URL: https://api.ugc.africa

This section documents the two real server-to-server surfaces developers integrate against: the Automation Actions API (campaign management) and the Payment Links API (shareable payment/invoice links). There is no separate "merchant" product - both sit on top of the same Campaign → Slot → CreatorProfile ad-distribution engine described in Getting Started.

Automation Actions API

/api/automation/actions/* - create and manage campaigns, fund them, and inspect slots, from your own backend or automation platform.

Authentication (any one of):

CredentialFormatWhere it comes from
Self-serve API keyAuthorization: Bearer UGSK_live_...Console → API Keys - see API key authentication
Automation connection keyAuthorization: Bearer UGAU_...Console → Automation - see Automation overview
Portal session JWTAuthorization: Bearer <jwt>Same token your logged-in dashboard session uses

See Campaign & Slot endpoints for the full reference and Fund a campaign for the funding call.

/payment-links/* - create shareable payment/invoice links (optionally with transaction protection), used for one-off invoicing or as a campaign-funding link for a third party.

Authentication: portal session JWT only (Authorization: Bearer <jwt>) - this is an account-holder endpoint, not a third-party integration credential.

See Payment Links endpoints for the full reference and Payment Links guide for the conceptual overview.

Response Format

There is no single universal envelope - a successful response is usually the resource itself (whatever shape that endpoint's reference documents, e.g. { "id": "...", "status": "..." }). A handful of endpoints that process a payment inline (card/crypto charges) return { "success": false, "error": "..." } on failure instead of throwing, with error as a plain string. Request-validation and auth failures instead use the standard { "statusCode": 400, "message": "...", "error": "Bad Request" } shape. Always check the HTTP status, not a success field. See Errors & troubleshooting.

Webhooks, not polling

Both surfaces emit events through the same Automation trigger catalog (campaign_created, campaign_funded, campaign_activated, slot_reserved, slot_approved, earnings_released, withdrawal_completed, and others) - subscribe once via POST /automation/webhooks/subscribe instead of polling for status changes. See Automation triggers for the full catalog (31 REST-hook names in AUTOMATION_TRIGGER_LIST; the Console picker shows the 19-event UGC subset) and the real X-UGC-Signature / X-UGC-Event-Id delivery headers.

Rate Limits

Endpoint TypeLimitWindow
Campaign actions100 requestsper minute
Payment Links100 requestsper minute
List endpoints200 requestsper minute

Responses include standard rate-limit headers:

code
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709639400

Common Errors

400INVALID_CURRENCY

Invalid Currency Code

The currency code provided is not supported.

Example Response
JSON
{
  "success": false,
  "error": {
    "code": "INVALID_CURRENCY",
    "message": "Currency code \"XYZ\" is not supported",
    "supportedCurrencies": [
      "USD",
      "EUR",
      "GBP",
      "GHS",
      "NGN"
    ]
  }
}

Solution: Use a valid ISO 4217 currency code. See our list of supported currencies.

400INSUFFICIENT_BALANCE

Insufficient Wallet Balance

The wallet does not have enough balance to complete this transaction.

Example Response
JSON
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance in USD wallet",
    "required": 5000,
    "available": 2500
  }
}

Solution: Add funds to your wallet or use a different payment method.

401UNAUTHORIZED

Authentication Required

The request requires authentication but none was provided.

Example Response
JSON
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

Solution: Include a valid API key or JWT token in the Authorization header.

429RATE_LIMIT_EXCEEDED

Rate Limit Exceeded

Too many requests have been made in a short period.

Example Response
JSON
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "retryAfter": 60
  }
}

Solution: Wait for the specified retry period before making another request. Consider implementing exponential backoff.

Did this solve your problem?