Tune API

Read-only access to call-quality metrics across the shops you cover — volume, script scores, booked rate, declined work and attribution. Resource-oriented URLs, query-string filters, JSON responses, standard HTTP status codes.

Overview

Every endpoint returns aggregates. There is no endpoint that lists individual calls, transcripts or customer data, and the scope that would grant that is separate from the one these endpoints use — a key that reports totals cannot enumerate the calls behind them.

Base URL: https://api.tune.srsandco.com

Authentication

Requests authenticate with a long-lived API key sent as a bearer token. There is no token exchange and nothing expires mid-session, so a client that can only attach a fixed header block works without a refresh cycle.

-H "Authorization: Bearer tune_sk_live_..."

A key is scoped twice: by what it may ask for (scopes, below) and by whose datait may see — an account, or an explicit list of stores. Both are checked on every request. Asking for a store outside the key's scope returns a 404, not a 403: existence itself is scoped, so the API never confirms a record it will not return.

Scopes

Versioning

The version is part of the path — /api/v1/… — never a header. Adding fields to a response is not a breaking change and will happen without a version bump, so clients should ignore unknown fields. Removing or renaming one means a new version.

Error responses

Errors carry a stable machine-readable code and a request id. Database messages are never surfaced.

{
  "error": {
    "code": "invalid_range",
    "message": "Range is limited to 400 days.",
    "request_id": "req_a57c695953e14f898de5c1ed"
  }
}

Every response — success or error — carries the same id in an x-request-id header.

Limits

The one hard bound in place is a 400-day maximum range on the metrics endpoints. They run synchronously behind a user action, not as batch jobs.

curl 'https://api.tune.srsandco.com/api/v1/stores' \
  -H "Authorization: Bearer $TUNE_API_KEY"

{
  "stores": [
    {
      "storeId": "e480609c-d8b6-4f2d-9999-e34ac39255f6",
      "storeName": "Rooster Ridge Car Care (Cypress)",
      "storeNumber": "1111",
      "timezone": "America/Chicago",
      "accountName": "Rooster Ridge Car Care",
      "accountSlug": "rooster-ridge"
    }
  ]
}

curl 'https://api.tune.srsandco.com/api/v1/metrics/stores?from=2026-08-01&to=2026-09-01' \
  -H "Authorization: Bearer $TUNE_API_KEY"

{
  "range": { "from": "2026-08-01T00:00:00+00:00", "to": "2026-09-01T00:00:00+00:00" },
  "stores": [
    {
      "storeId": "41b2914a-c26d-426f-a994-5c5b7336961b",
      "storeName": "Rooster Ridge Car Care (Pearland)",
      "storeNumber": "1714",
      "accountName": "Rooster Ridge Car Care",
      "accountSlug": "rooster-ridge",
      "calls": 2397,
      "inbound": 1281,
      "outbound": 1116,
      "answered": 2397,
      "avgDurationSeconds": 162,
      "avgScore": 70.5,
      "scoredCalls": 1999,
      "checkedCalls": 1342,
      "bookedCalls": 667,
      "bookedPct": 49.7,
      "authorizedCents": 61764630,
      "declinedAskedForCents": 6153903,
      "declinedRecommendedCents": 87104091,
      "unattributed": 915,
      "unattributedPct": 38.2,
      "pipeline": {
        "recordingPending": 0,
        "transcriptPending": 0,
        "recordingUnavailableUpstream": 32,
        "recordingFailedOther": 0
      },
      "callTypes": {
        "general": 1544, "other": 323, "isolate_broken": 211,
        "anytime": 124, "pmi": 120, "unscored": 75
      },
      "daily": [
        { "day": "2026-07-31", "calls": 3,  "avgScore": 38.3 },
        { "day": "2026-08-01", "calls": 83, "avgScore": 57 }
      ]
    }
  ]
}

curl 'https://api.tune.srsandco.com/api/v1/metrics/reps?from=2026-08-01&to=2026-09-01' \
  -H "Authorization: Bearer $TUNE_API_KEY"

{
  "range": { "from": "2026-08-01T00:00:00+00:00", "to": "2026-09-01T00:00:00+00:00" },
  "reps": [
    {
      "employeeId": "0e2f9c0f-67f9-4aec-99f7-a364e5f826b9",
      "name": "Bailey C.",
      "storeId": "41b2914a-c26d-426f-a994-5c5b7336961b",
      "storeName": "Rooster Ridge Car Care (Pearland)",
      "calls": 503,
      "avgDurationSeconds": 166,
      "avgScore": 68.8,
      "scoredCalls": 485,
      "checkedCalls": 385,
      "bookedCalls": 177,
      "bookedPct": 46,
      "confidentAttribution": 503
    }
  ]
}

What the numbers mean

Four things that are easy to get wrong without being told.

Getting a key

Keys are issued by the Tune team. Ask for one and say which stores or account the integration needs and what it is for — a key is scoped to exactly that, so a narrower request is quicker to grant.

You will receive the key once, in plaintext. Store it as a secret in your deployment environment, never in source control. Tune keeps only a hash of it, so if it is lost it cannot be recovered or re-sent — a replacement has to be issued.

Keys expire after a year by default. Rotation needs no coordinated cutover: ask for the replacement, deploy it, then tell us to revoke the old one. Both work at once until you do.

If a key is exposed, say so immediately rather than waiting for the rotation window. Revocation takes effect on the next request.