REST API overview

The AIsoule REST API lets you programmatically send messages, manage contacts, and integrate with your existing systems.

Base URL

https://app.aisoule.com/api

All API endpoints are relative to this base URL.

Authentication

API Key authentication

1. Go to Settings → API Keys
2. Click "New API Key"
3. Enter a name (e.g., "CRM Integration")
4. Set an expiry date (optional)
5. Copy the generated key — it's only shown once!

Include the API key in every request:

curl -H "X-API-Key: your_api_key_here" \
  https://app.aisoule.com/api/contacts

Cookie-based authentication

For browser-based integrations, you can also use session cookies from the login endpoint:

curl -X POST https://app.aisoule.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your_password"}'

Request format

• Content-Type: application/json
• Method: GET (read), POST (create), PUT (update), DELETE (remove)
• Response format: JSON envelope

Response envelope

All responses follow this format:

{
  "data": { ... },
  "status": "success"
}

Error responses:

{
  "message": "Error description",
  "status": "error"
}

Your first API call

List your contacts:

curl -H "X-API-Key: your_key" \
  https://app.aisoule.com/api/contacts

Response:

{
  "data": {
    "contacts": [
      {
        "id": "uuid",
        "phone_number": "+919876543210",
        "name": "John Doe",
        "tags": ["customer"],
        "stage": "Customer"
      }
    ],
    "total": 150,
    "page": 1
  }
}

Available endpoints

Rate limits

• 100 requests per minute per API key
• 10 requests per second burst limit
• Rate limit headers included in responses:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

SDKs and libraries

Currently, we provide a REST API. You can use any HTTP client:

• JavaScript: fetch, axios
• Python: requests, httpx
• PHP: Guzzle
• Go: net/http

Security best practices

1. Never expose API keys in frontend code — Use server-side only
2. Rotate keys regularly — Create new keys and revoke old ones
3. Use minimal permissions — Create keys with only the access needed
4. Monitor usage — Check API key activity in Settings → API Keys
5. Use HTTPS only — All API calls must use HTTPS