SaveCall API v1

API Overview

Concrete use cases:

• resolve a tel: link into a likely contact name plus alternatives
• choose the recommended capture mode for a launch country
• submit post-resolution feedback to improve product loops
• start a Stripe checkout or billing portal flow tied to a SaveCall tenant

Quickstart

Authentication is header-based via X-SaveCall-Api-Key. When you supply a clientRef to /v1/resolve, the API key must be bound to that same client reference.

clientRef is the SaveCall tenant/customer identifier used across checkout, webhook state, billing state resolution, and resolve enforcement.

Minimal health check

curl -s https://your-savecall-host/health

Minimal resolve example

curl -s -X POST https://your-savecall-host/v1/resolve \
  -H "Content-Type: application/json" \
  -H "X-SaveCall-Api-Key: sca_staging_..." \
  -d '{
    "rawNumber": "+351239410000",
    "userCountry": "PT",
    "searchCountry": "PT",
    "searchLanguage": "pt",
    "captureMode": "EXTENSION",
    "sourceType": "TEL_LINK",
    "browser": "firefox",
    "clientRef": "staging-tenant-001",
    "origin": {
      "url": "https://www.uc.pt/contactos",
      "title": "Universidade de Coimbra — Contactos",
      "host": "www.uc.pt",
      "nearHeading": "Contactos",
      "pageExcerpt": "Universidade de Coimbra contactos telefónicos"
    },
    "preferences": {
      "confirmBeforeSaving": false,
      "allowNumberOnly": true,
      "preferEntityNameForTelLink": true
    }
  }'

Note: clientRef is enforced directly in the server code for /v1/resolve, but it is not yet part of the published contract DTO file. This docs page reflects the current live server behavior rather than an idealized contract-only view.

Example resolve response shape

{
  "resolutionId": "res_...",
  "status": "RESOLVED",
  "recommendedAction": "SAVE_CONTACT",
  "userMessage": "Resolved with strong page context",
  "allowNumberOnly": true,
  "normalizedNumber": "+351239410000",
  "confidence": {
    "score": 0.92,
    "level": "HIGH",
    "label": "High confidence"
  },
  "bestMatch": {
    "id": "match_...",
    "displayName": "Universidade de Coimbra",
    "phoneE164": "+351239410000",
    "sourceUrl": "https://www.uc.pt/contactos",
    "sourceLabel": "page context",
    "entityType": "institution",
    "reasonSummary": "Strong origin and page signals"
  },
  "alternatives": [],
  "contextProvenance": "origin+page",
  "debugTraceId": "trace_..."
}

Billing checkout example

curl -s -X POST https://your-savecall-host/billing/checkout \
  -H "Content-Type: application/json" \
  -d '{"plan":"TEAM","clientRef":"staging-tenant-001"}'

{
  "stub": false,
  "plan": "TEAM",
  "clientRef": "staging-tenant-001",
  "checkoutConfigured": true,
  "checkoutSessionId": "cs_...",
  "checkoutUrl": "https://checkout.stripe.com/..."
}

The plan field above reflects the request and current server-side billing identifiers. It should not be read as final public pricing or finalized commercial packaging.

JavaScript example

const response = await fetch("https://your-savecall-host/v1/resolve", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-SaveCall-Api-Key": "sca_staging_..."
  },
  body: JSON.stringify({
    rawNumber: "+351239410000",
    userCountry: "PT",
    searchCountry: "PT",
    searchLanguage: "pt",
    captureMode: "EXTENSION",
    sourceType: "TEL_LINK",
    clientRef: "staging-tenant-001"
  })
});
const data = await response.json();

Python example

import requests

response = requests.post(
    "https://your-savecall-host/v1/resolve",
    headers={
        "Content-Type": "application/json",
        "X-SaveCall-Api-Key": "sca_staging_...",
    },
    json={
        "rawNumber": "+351239410000",
        "userCountry": "PT",
        "searchCountry": "PT",
        "searchLanguage": "pt",
        "captureMode": "EXTENSION",
        "sourceType": "TEL_LINK",
        "clientRef": "staging-tenant-001",
    },
)
print(response.status_code, response.json())

API Reference

{
  "status": "ok",
  "service": "save-call-api",
  "version": "v1-file-backed-runtime"
}

{
  "countryCode": "PT",
  "recommendedMode": "EXTENSION",
  "reason": "Current benchmark policy favours EXTENSION for PT",
  "benchmarks": [],
  "defaultSearchCountry": "PT",
  "defaultSearchLanguage": "pt",
  "sourceLabel": "policy_json",
  "fallbackUsed": false
}

{
  "accepted": true,
  "message": "Feedback accepted"
}

{
  "plan": "TEAM",
  "clientRef": "staging-tenant-001"
}

{
  "clientRef": "staging-tenant-001"
}

{
  "stub": false,
  "portalConfigured": true,
  "portalReturnUrl": "https://example.com/account",
  "clientRef": "staging-tenant-001",
  "resolvedVia": "clientRef",
  "customerId": "cus_...",
  "portalSessionId": "bps_...",
  "portalUrl": "https://billing.stripe.com/..."
}

{
  "stub": false,
  "clientRef": "staging-tenant-001",
  "customerId": "cus_UEfRC62pbeT6Fw",
  "subscriptionId": "sub_1TGC6PFWBKL8DaOfumw75oBJ",
  "plan": null,
  "priceId": null,
  "status": "active",
  "isActive": true,
  "resolvedFrom": "webhook_event_store:checkout.session.completed",
  "resolvedAtMs": 1774762899300,
  "sourceEventId": "evt_1TGC6QFWBKL8DaOfDZddiblc",
  "sourceEventReceivedAt": 1774762899300
}

Auth & Quotas

X-SaveCall-Api-Key

The server reads the API key from the X-SaveCall-Api-Key header. API keys are bound to specific clientRef values in the API runtime store.

clientRef binding

When a clientRef is present on /v1/resolve, the request flows through this enforcement chain:

1. API key must be present
2. API key must be known
3. API key must match the same clientRef
4. billing must be active for that clientRef
5. quota evaluation is then applied using the server's current billing/usage interpretation

TRANSITIONAL vs STRICT

Common auth errors

{"error":true,"code":"missing_api_key","message":"Header X-SaveCall-Api-Key is required when clientRef is supplied"}
{"error":true,"code":"invalid_api_key","message":"The provided API key is not recognised"}
{"error":true,"code":"client_ref_mismatch","clientRef":"staging-tenant-001","message":"The API key is not authorised for clientRef \"staging-tenant-001\""}

Quota headers

The server emits these headers once quota evaluation is reached on /v1/resolve:

• X-SaveCall-Plan
• X-SaveCall-Quota-Limit
• X-SaveCall-Quota-Used
• X-SaveCall-Quota-Remaining

X-SaveCall-Plan: unknown
X-SaveCall-Quota-Limit: 50
X-SaveCall-Quota-Used: 37
X-SaveCall-Quota-Remaining: 13

Errors

Current error responses are JSON objects. Two shapes exist today:

• generic ack-style errors from helper paths, usually {"accepted":false,"message":"..."}
• structured enforcement errors from /v1/resolve, with error, code, and message

{
  "error": true,
  "code": "inactive_subscription",
  "clientRef": "staging-tenant-001",
  "message": "No active subscription for clientRef \"staging-tenant-001\""
}

Common codes:

• missing_client_ref
• missing_api_key
• invalid_api_key
• client_ref_mismatch
• inactive_subscription
• plan_quota_exceeded

What integrators should do:

• treat 400 as request-shape or strict-mode input issues
• treat 401/403 as auth or tenant-binding failures
• treat 402 as billing-state remediation needed
• treat 429 as quota exhaustion and surface quota headers if present
• treat quota and plan identifiers as operational signals rather than final commercial labels
• log debugTraceId from successful resolve responses when debugging outcome quality

Versioning & Changelog

The current public surface is documented as API v1. Endpoint names are already versioned under /v1/ where appropriate.

Breaking changes should be introduced conservatively. Because the API is still in a staging-to-prelaunch phase, anything not yet marked stable in these docs should be treated as subject to tightening rather than frozen forever.

OpenAPI draft status

The linked openapi.yaml is a conservative draft to help integrators explore the surface. It is not yet the sole canonical contract source, and current live server behavior may still be described more precisely in these docs where operational truth exceeds contract DTO publication.

Initial changelog

• v1 current: health, mode recommendation, resolve, feedback, billing checkout/portal/state, Stripe webhook integration
• Current prelaunch additions: clientRef discipline, API key enforcement, billing gating, quota headers, runtime-backed billing state
• Still evolving: final commercial language, legal text, security/privacy publication wording, backend hardening details

Draft pages