Developer Platform

Slokoto API

Build custom integrations with the Slokoto REST API and Webhooks. Manage leads programmatically, receive real-time events, and extend Slokoto to fit your workflow.

Base URLhttps://slokoto.com/api/v1

Authentication

Slokoto uses OAuth2 Client Credentials for API authentication. Generate your credentials in Integrations → Custom → REST API in your Slokoto dashboard.

Step 1: Get an Access Token

Exchange your client_id and client_secret for a short-lived bearer token (1 hour).

cURL
curl -X POST https://slokoto.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "slk_ci_your_client_id",
    "client_secret": "slk_cs_your_client_secret"
  }'
Response
{
  "data": {
    "access_token": "slk_at_...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "leads.read leads.write"
  }
}

Step 2: Use the Token

Include the token in the Authorization header of all API requests.

cURL
curl https://slokoto.com/api/v1/leads \
  -H "Authorization: Bearer slk_at_your_access_token"
JavaScript
const response = await fetch('https://slokoto.com/api/v1/leads', {
  headers: {
    'Authorization': 'Bearer slk_at_your_access_token',
  },
});
const { data, meta } = await response.json();
Python
import requests

response = requests.get(
    'https://slokoto.com/api/v1/leads',
    headers={'Authorization': 'Bearer slk_at_your_access_token'},
)
data = response.json()

REST Endpoints

All endpoints are workspace-scoped. Your API client can only access leads within its workspace.

Webhooks

Configure webhook endpoints in Integrations → Custom → Webhooks to receive real-time HTTP POST notifications when events occur in your workspace.

Event Types

EventDescription
lead.createdA new lead was created
lead.updatedA lead's fields were modified
lead.status_changedA lead's status changed (active, won, lost, archived)
lead.assignedA lead was assigned to a team member
lead.stage_changedA lead moved to a different pipeline stage
lead.deletedA lead was permanently deleted

Payload Format

Webhook Payload
{
  "event": "lead.created",
  "created_at": "2026-03-19T14:30:00Z",
  "data": {
    "lead": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john@acme.com",
      "name": "John Smith",
      "company": "Acme Corp",
      "status": "active",
      ...
    }
  }
}

Headers

HeaderDescription
X-Slokoto-SignatureHMAC-SHA256 signature for payload verification
X-Slokoto-EventThe event type (e.g., lead.created)
X-Slokoto-DeliveryUnique delivery ID for deduplication
Content-TypeAlways application/json

Verifying Signatures

Every webhook request includes an X-Slokoto-Signature header with the format t=timestamp,v1=hex_signature. Verify it to ensure the request is genuine.

Node.js
const crypto = require('crypto');

function verifyWebhook(payload, signatureHeader, secret) {
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).slice(2);
  const signature = parts.find(p => p.startsWith('v1=')).slice(3);

  // Check timestamp is within 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Webhook timestamp too old');
  }

  // Compute expected signature
  const signedContent = timestamp + '.' + payload;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedContent)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}
Python
import hmac
import hashlib
import time

def verify_webhook(payload: str, signature_header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in signature_header.split(','))
    timestamp = parts['t']
    signature = parts['v1']

    # Check timestamp tolerance
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError('Webhook timestamp too old')

    # Compute expected
    signed = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(), signed.encode(), hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Retry Policy

If your endpoint returns a non-2xx status code or times out (10 seconds), Slokoto retries with exponential backoff:

AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry (final)12 hours

Rate Limits

API requests are rate-limited to 60 requests per minute per API client. Rate limit information is included in response headers:

HeaderDescription
X-RateLimit-LimitMaximum requests per window (60)
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the window resets

When rate limited, the API returns 429 Too Many Requests. Wait until the reset time before retrying.

Error Handling

All errors follow a consistent format:

Error Response
{
  "error": {
    "code": "not_found",
    "message": "Lead not found"
  }
}

Error Codes

HTTPCodeDescription
400invalid_requestMalformed request body or parameters
401unauthorizedMissing or invalid access token
403forbiddenToken lacks required scope
404not_foundResource does not exist or is not in your workspace
409duplicate_leadA lead with this email already exists
422validation_errorRequest body fails validation
429rate_limitedToo many requests — slow down
500server_errorInternal server error — retry or contact support
502ai_errorAI provider error (ai-update endpoint only)