Get started

Getting started

Create an API key, authenticate your first request, and start building with JagCall in under five minutes.

Quickstart

  1. 1

    Create an API key

    1. Log in to your JagCall dashboard.
    2. Switch the sidebar to Settings and open API Keys (under Tools).
    3. Click Create Key.
    4. Give it a descriptive name (e.g. "Backend Server") and, optionally, an expiry.
    5. Under Access, tick Full access or choose only the scopes the key needs (listing agents needs the agents read scope).
    6. Copy the key immediately — it will not be shown again.

    Keep your key secret

    Never commit an API key to version control or expose it in client-side code. Use environment variables in production.
  2. 2

    Authenticate requests

    Include your API key as a Bearer token in the Authorization header of every request. The base URL is https://jagcall.com/v1/.

    http
    Authorization: Bearer jc_live_abc123...
  3. 3

    Make your first call

    List the agents on your account to verify everything works. List endpoints return a page with items, total, limit, and offset.

    curl
    curl -X GET https://jagcall.com/v1/agents \  -H "Authorization: Bearer jc_live_abc123..." \  -H "Content-Type: application/json"
    python
    import requestsAPI_KEY = "jc_live_abc123..."BASE_URL = "https://jagcall.com/v1"response = requests.get(    f"{BASE_URL}/agents",    headers={        "Authorization": f"Bearer {API_KEY}",        "Content-Type": "application/json",    },)page = response.json()for agent in page["items"]:    print(f"{agent['name']} ({agent['id']})")
    node.js
    const API_KEY = "jc_live_abc123...";const BASE_URL = "https://jagcall.com/v1";const response = await fetch(`${BASE_URL}/agents`, {  headers: {    Authorization: `Bearer ${API_KEY}`,    "Content-Type": "application/json",  },});const page = await response.json();page.items.forEach((agent) => {  console.log(`${agent.name} (${agent.id})`);});
    json
    {  "items": [{ "id": "...", "name": "Front desk", "status": "active", ... }],  "total": 1,  "limit": 50,  "offset": 0}

Rate limiting

Rate limits vary by endpoint to ensure fair usage, and are counted per organization, not per key. When you exceed a limit, the API returns 429 Too Many Requests with a Retry-After header.

EndpointLimit
GET endpoints (lists, details, transcripts)200/min
POST /v1/calls30/min
POST /v1/sms60/min
POST /v1/agents (and other writes)30/min
POST /v1/phone-numbers/search10/min
POST /v1/phone-numbers (provisioning)5/min

Error responses

All errors follow a consistent JSON format with an error code, a human-readable message, an HTTP status, and a request ID to quote when you contact support.

json
{  "error": {    "code": "unauthorized",    "message": "Invalid or expired API key",    "status": 401,    "request_id": "...",    "details": null  }}
StatusMeaning
400Bad request — invalid parameters
401Unauthorized — missing, invalid, or expired API key
402Insufficient balance — add credit in Billing
403Forbidden — the key lacks the required scope
404Not found — resource does not exist
409Conflict — the request clashes with the resource's current state
422Unprocessable entity — validation error
429Too many requests — rate limit exceeded
500Internal server error — contact support

Still need help?

Can't find what you're looking for? Send us a message and our team will get back to you.

Contact support