HTTP / REST

Call the Cheqpoint API directly from any language using plain HTTP. No SDK required.

Submit a request for approval (blocking pattern)

cURL

# POST to /api/approvals/request — creates a request and returns its ID.
# Auth: x-api-key header with your Connection Key.
curl -X POST https://app.cheqpoint.co/api/approvals/request \
  -H "Content-Type: application/json" \
  -H "x-api-key: cq_live_xxxxxxxxxxxx" \
  -d '{
    "action": "process_refund",
    "summary": "Refund $120.00 for order #8842",
    "details": { "orderId": "8842", "amount": 120.00, "currency": "USD" },
    "riskLevel": "high"
  }'

# Response:
# { "id": "req_abc123", "status": "PENDING" }

Poll for the decision

cURL

# Poll until status is no longer PENDING
curl https://app.cheqpoint.co/api/approvals/req_abc123 \
  -H "x-api-key: cq_live_xxxxxxxxxxxx"

# Response when approved:
# {
#   "id": "req_abc123",
#   "status": "APPROVED",
#   "modifiedDetails": null,
#   "decisionNote": "Looks good",
#   "decidedAt": "2025-03-18T14:32:00.000Z"
# }

Short-wait with maxWaitMs (synchronous pattern)

cURL

# POST to /api/webhooks/inbound with maxWaitMs for a server-side short wait.
# The server holds the connection open up to maxWaitMs (capped at 10,000 ms).
# If decided in time, returns the decision inline. Otherwise returns "pending".
curl -X POST https://app.cheqpoint.co/api/webhooks/inbound \
  -H "Content-Type: application/json" \
  -H "x-api-key: cq_live_xxxxxxxxxxxx" \
  -d '{
    "action": "process_refund",
    "summary": "Refund $120.00 for order #8842",
    "details": { "orderId": "8842", "amount": 120.00 },
    "maxWaitMs": 10000
  }'

# Response if decided inline:
# { "status": "approved", "approvalId": "req_abc123", "modifiedDetails": null }
# Response if still pending:
# { "status": "pending", "approvalId": "req_abc123", "reviewUrl": "https://..." }

Fire-and-forget with callbackUrl

cURL

# POST to /api/webhooks/inbound with callbackUrl for async delivery.
# Returns immediately with the current status. If "pending", Cheqpoint will
# POST the final decision to your callbackUrl when a reviewer decides.
curl -X POST https://app.cheqpoint.co/api/webhooks/inbound \
  -H "Content-Type: application/json" \
  -H "x-api-key: cq_live_xxxxxxxxxxxx" \
  -d '{
    "action": "process_refund",
    "summary": "Refund $120.00 for order #8842",
    "details": { "orderId": "8842", "amount": 120.00 },
    "callbackUrl": "https://your-backend.example.com/webhooks/cheqpoint"
  }'

# Cheqpoint POSTs this to your callbackUrl when decided:
# {
#   "approvalId": "req_abc123",
#   "status": "approved",
#   "modifiedDetails": null,
#   "decisionNote": "Approved."
# }

Python example with polling

python

import requests, time

CONNECTION_KEY = "cq_live_xxxxxxxxxxxx"
BASE_URL = "https://cheqpoint.co"

# Submit
resp = requests.post(
    f"{BASE_URL}/api/approvals/request",
    headers={"x-api-key": CONNECTION_KEY, "Content-Type": "application/json"},
    json={
        "action": "process_refund",
        "summary": "Refund $500 for order #12345",
        "details": {"orderId": "12345", "amount": 500},
        "riskLevel": "high",
    }
)
request_id = resp.json()["id"]

# Poll
for _ in range(60):  # max 5 min
    time.sleep(5)
    decision = requests.get(
        f"{BASE_URL}/api/approvals/{request_id}",
        headers={"x-api-key": CONNECTION_KEY}
    ).json()

    if decision["status"] != "PENDING":
        print(f"Decision: {decision['status']}")
        break

Receiving callbacks securely

When Cheqpoint POSTs a decision to your callbackUrl, the request includes the header User-Agent: Cheqpoint-Callback/1.0. To verify authenticity, check that the approvalId in the body matches a request you previously submitted, and confirm the decision by polling GET /api/approvals/{approvalId} before acting on it.

Choosing a pattern

Blocking (POST + poll): simplest — use when your environment can hold an open connection for minutes (e.g., background workers, cron jobs).
Short-wait (maxWaitMs): best for real-time APIs where you can tolerate a few seconds of latency. Falls back to polling if not decided in time.
Async (callbackUrl): best for webhooks and event-driven systems where blocking is not acceptable. Your system resumes when the decision arrives.