Sign Up arrow right
Public API v1

Tools API

Browse working tools and picture packs, purchase them with wallet balance, and deliver protected downloads to your integration.

Start integrating View Markdown
POST https://www.socanum.com/api/v1/tools/orders 
{
  "tool_id": 12,
  "idempotency_key": "tool-order-20260502-0001"
}

Documentation Hub

API Collections

Shared documentation system for every public API collection.
Available Logs API Browse categories, buy logs, and review orders. Available Numbers API Phone number catalog, purchase, and activation workflows. Available Boosting API Social boosting products, checkout, and order tracking. Available Tools API Developer tooling products and delivery endpoints.

Base URL

Production Endpoint

All paths in this guide are relative to the current API base URL. Protected endpoints require bearer authentication.

https://www.socanum.com/api/v1

Security

Authentication

Bearer API Key

Generate your API key from API Access. Copy it immediately; it is displayed only once. Generating a new key revokes the previous key.

Required headers 
Accept: application/json
Authorization: Bearer YOUR_API_KEY_HERE
401 Response
{
  "success": false,
  "status": 401,
  "message": "Unauthenticated. Please provide a valid bearer token.",
  "code": "UNAUTHENTICATED"
}
GET

Wallet Balance

/wallet

Returns the authenticated user's wallet balance. Requires bearer authentication.

cURL Request 
curl -X GET "https://www.socanum.com/api/v1/wallet" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"
200 Response
{
  "success": true,
  "data": {
    "balance": "12500.00",
    "currency": "NGN"
  }
}

Local Delivery

Wallet-Backed Tool Checkout

The Tools API uses Socanum inventory only. Your integration lists active tools, places a wallet-backed order, then downloads owned files through a protected endpoint.

No external API Idempotent checkout Protected downloads Order history
GET

List Tools

/tools

Returns active working tools and picture packs. Use type to filter by tool or picture.

Query Type Description
typestringOptional. Either tool or picture.
per_pageintegerOptional. Values from 1 to 100. Defaults to 25.
cURL Request 
curl -G "https://www.socanum.com/api/v1/tools" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  --data-urlencode "type=tool"
200 Response
{
  "success": true,
  "data": [
    {
      "id": 12,
      "type": "tool",
      "name": "Automation Toolkit",
      "description": "Ready-to-use workflow files.",
      "image": "/storage/uploads/tools/example.png",
      "price": "5000.00",
      "currency": "NGN",
      "number_of_pictures": 0,
      "number_of_videos": 0,
      "available": true
    }
  ]
}
GET

Get Tool

/tools/{tool_id}

Returns one active tool or picture pack. Delivery links and protected file paths are only available after purchase.

POST

Purchase Tool

/tools/orders

Purchases a tool, deducts the wallet balance, creates a completed order, and returns a protected download URL.

Do not send price from your integration. Socanum calculates the charge from the current tool price. Use a unique idempotency_key for every checkout attempt.
cURL Request 
curl -X POST "https://www.socanum.com/api/v1/tools/orders" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":12,"idempotency_key":"tool-order-20260502-0001"}'
201 Response
{
  "success": true,
  "data": {
    "order_id": "tools-api-ABC1234567-1777560000",
    "status": "completed",
    "tool_id": 12,
    "tool_name": "Automation Toolkit",
    "tool_type": "tool",
    "quantity": 1,
    "price": "5000.00",
    "currency": "NGN",
    "balance_after": "15000.00",
    "download_url": "https://www.socanum.com/api/v1/tools/orders/tools-api-ABC1234567-1777560000/download"
  }
}
GET

List Tool Orders

/tools/orders

Returns the authenticated user's tool purchase history.

GET

Get Tool Order

/tools/orders/{order_id}

Returns one tool order owned by the authenticated account, including the protected download endpoint.

GET

Download Tool

/tools/orders/{order_id}/download

Downloads the purchased tool files. If a tool is delivered by a managed external link instead of protected files, the endpoint returns that delivery URL as JSON.

cURL Request 
curl -L "https://www.socanum.com/api/v1/tools/orders/tools-api-ABC1234567-1777560000/download" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  --output tool-assets.zip

Failure Handling

Error Format

JSON errors
Error Response
{
  "success": false,
  "status": 409,
  "message": "This tool has already been purchased by this account.",
  "code": "TOOL_ALREADY_OWNED"
}
UNAUTHENTICATEDThe bearer token is missing, invalid, or revoked.
VALIDATION_FAILEDOne or more request fields are missing or invalid.
TOOL_NOT_FOUNDThe tool does not exist or is unavailable.
TOOL_ALREADY_OWNEDThe account has already purchased this tool.
TOOL_ORDER_NOT_FOUNDThe order ID does not belong to the authenticated account.
TOOL_DOWNLOAD_NOT_AVAILABLENo downloadable files are available for the purchased tool.
INSUFFICIENT_BALANCEThe wallet balance cannot cover the calculated price.
IDEMPOTENCY_KEY_REUSEDThe key was used for a different request body.