Skip to main content

​
Prerequisites

Before you start, make sure you have:
Organization with API plan or higher
Your API Key and HMAC Secret
Your organization’s subdomain
If you don’t have an API plan yet, upgrade your subscription to get started.

​
Step 1: Get Your Credentials

  1. Go to Settings > Applications > API Keys
  2. Click “Create New API Key”
  3. Copy and save your credentials securely

​
Step 2: Make Your First Request

Let’s fetch your customer list: 
#!/bin/bash

API_KEY="ak_your_api_key_here"
HMAC_SECRET="your_hmac_secret_here"
BASE_URL="https://your-subdomain.unicyfalcon.com/api/v1"

METHOD="GET"
URI="/api/v1/customers"
BODY=""
TIMESTAMP=$(date +%s)

# Generate HMAC signature
PAYLOAD="${METHOD}|${URI}|${BODY}|${TIMESTAMP}"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$HMAC_SECRET" -binary | base64)

# Make the request
curl -X GET \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  "${BASE_URL}/customers"

​
Step 3: Verify the Response

A successful response will look like this: 
{
  "success": true,
  "data": [
    {
      "id": "9d3f4b2a-8c7e-4d1b-9f3a-5e6c7d8a9b0c",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "555-1234",
      "company_name": "Acme Corp",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 42
  }
}

​
Common Issues

Solution: Upgrade your organization to API plan or higher at Billing Settings
Solution:
  • Double-check your API Key and HMAC Secret
  • Verify the payload format: METHOD|URI|BODY|TIMESTAMP
  • Ensure timestamp is current (within 5 minutes)
Solution: You’ve exceeded your rate limit. Wait for the retry period (check Retry-After header) or upgrade your plan for higher limits.

​
Next Steps

Create an Order

Learn how to create orders via API

Track Deliveries

Monitor delivery status in real-time

Error Handling

Handle API errors gracefully

Rate Limiting

Optimize your API usage