> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicyfalcon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Make your first API call in under 5 minutes

## Prerequisites

Before you start, make sure you have:

<Check>Organization with **API plan or higher**</Check>
<Check>Your **API Key** and **HMAC Secret**</Check>
<Check>Your organization's **subdomain**</Check>

<Warning>
  If you don't have an API plan yet, [upgrade your subscription](https://app.unicyfalcon.com/billing) to get started.
</Warning>

## Step 1: Get Your Credentials

1. Go to [Settings > Applications > API Keys](https://app.unicyfalcon.com/settings/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:

<CodeGroup>
  ```bash cURL theme={null}
  #!/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"
  ```

  ```php PHP theme={null}
  <?php

  $apiKey = 'ak_your_api_key_here';
  $hmacSecret = 'your_hmac_secret_here';
  $baseUrl = 'https://your-subdomain.unicyfalcon.com/api/v1';

  $method = 'GET';
  $uri = '/api/v1/customers';
  $body = '';
  $timestamp = time();

  // Generate HMAC signature
  $payload = $method . '|' . $uri . '|' . $body . '|' . $timestamp;
  $signature = base64_encode(hash_hmac('sha256', $payload, $hmacSecret, true));

  // Make the request
  $ch = curl_init($baseUrl . '/customers');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Content-Type: application/json',
      'X-API-Key: ' . $apiKey,
      'X-Timestamp: ' . $timestamp,
      'X-Signature: ' . $signature,
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);
  ```

  ```python Python theme={null}
  import requests
  import hmac
  import hashlib
  import base64
  import time

  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 = str(int(time.time()))

  # Generate HMAC signature
  payload = f'{method}|{uri}|{body}|{timestamp}'
  signature = base64.b64encode(
      hmac.new(hmac_secret.encode(), payload.encode(), hashlib.sha256).digest()
  ).decode()

  # Make the request
  headers = {
      'Content-Type': 'application/json',
      'X-API-Key': api_key,
      'X-Timestamp': timestamp,
      'X-Signature': signature
  }

  response = requests.get(f'{base_url}/customers', headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
  const crypto = require('crypto');

  const apiKey = 'ak_your_api_key_here';
  const hmacSecret = 'your_hmac_secret_here';
  const baseUrl = 'https://your-subdomain.unicyfalcon.com/api/v1';

  const method = 'GET';
  const uri = '/api/v1/customers';
  const body = '';
  const timestamp = Math.floor(Date.now() / 1000).toString();

  // Generate HMAC signature
  const payload = `${method}|${uri}|${body}|${timestamp}`;
  const signature = crypto
    .createHmac('sha256', hmacSecret)
    .update(payload)
    .digest('base64');

  // Make the request
  const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature
  };

  axios.get(`${baseUrl}/customers`, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error.response.data));
  ```
</CodeGroup>

## Step 3: Verify the Response

A successful response will look like this:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="403 Forbidden - Plan Insufficient">
    **Solution:** Upgrade your organization to API plan or higher at [Billing Settings](https://app.unicyfalcon.com/billing)
  </Accordion>

  <Accordion title="401 Unauthorized - Invalid Signature">
    **Solution:**

    * Double-check your API Key and HMAC Secret
    * Verify the payload format: `METHOD|URI|BODY|TIMESTAMP`
    * Ensure timestamp is current (within 5 minutes)
  </Accordion>

  <Accordion title="429 Too Many Requests">
    **Solution:** You've exceeded your rate limit. Wait for the retry period (check `Retry-After` header) or upgrade your plan for higher limits.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create an Order" icon="cart-plus" href="/api-reference/orders/create">
    Learn how to create orders via API
  </Card>

  <Card title="Track Deliveries" icon="location-dot" href="/api-reference/deliveries/list">
    Monitor delivery status in real-time
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle API errors gracefully
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/guides/rate-limiting">
    Optimize your API usage
  </Card>
</CardGroup>