SolarKnock Reporting API

Overview

The Reporting API exposes the source data behind every screen in SolarKnock — the same rows that power your leaderboard, your stats sheet, your manager dashboard, and your lead pipeline. You get the records, not the aggregates, so your warehouse can roll them up however you like.

Base URL: https://app.solarknock.com/api/v1/reporting

Reads (every GET endpoint below) are enabled by default for every organization. Writes (POST + PATCH /knocks) require an org admin to explicitly enable them under Profile → API & Integrations — turned off by default so a stale read token cannot accidentally start mutating data.

Authentication

Every request carries an API key as a Bearer token. Keys look like sk_live_… and are scoped to exactly one organization — there is no ?orgId= parameter on any endpoint, ever.

Send it on every request:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Send the key exactly as issued, including the sk_live_ prefix — it is hashed verbatim, so a trimmed or altered key returns 401 INVALID_KEY.

Metric Definitions

These are the exact definitions the in-app dashboard, leaderboard, and map use. If you roll the API data up any other way, your numbers will not match what your managers see inside SolarKnock.

Making Requests

There is no single parameter set that works on every endpoint — each one accepts its own list. The tables below are authoritative. On the list endpoints, any parameter not in that endpoint's list returns 400 INVALID_PARAM naming the offending parameter and listing what the endpoint does accept.

Common parameters

What each endpoint accepts

Worth reading twice: only /knocks, /leads and /appointments support since/until. /daily-stats has no updated_at filter — window it with date_from/date_to. /usage-days has no time filter at all. /users has no updated_at, so it has no incremental mode — re-pull it in full. /counties takes no parameters and is not paginated.

Accepted aliases

The guesses integrators actually reach for are accepted and applied (the filter really takes effect) rather than rejected:

Aliases are a convenience, not the contract — write new integrations against the canonical names above. per_page and page_size are accepted as aliases for limit. Offset position parameters (page, offset, skip) cannot be honored by a cursor API: a first-page value (page=1, offset=0, skip=0) is accepted and ignored with a Warning response header, and any other value returns 400. See Pagination.

Response envelope

Every list response shares the same shape:

{
  "data": [ /* rows for this page */ ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjAxMjM0NTY3...=",
    "has_more": true
  },
  "meta": {
    "org_id": "f7a...",
    "fetched_at": "2026-05-01T17:32:14Z",
    "row_count": 500
  }
}

When has_more is false, next_cursor is null. Your sync loop is simply: while (cursor) { fetch(cursor) }.

Dates & Time Zones

Getting this wrong is the most common cause of "the API doesn't match my dashboard". There are two kinds of date field here and they are not interchangeable.

• since/until compare against updated_at, never created_at. They are a change feed, not a creation window.
• knock_date on rows created before 2026-04-16 may reflect UTC rather than device-local — a historical limitation of older clients. Data since then is device-local.

Pagination & Incremental Sync

This API is cursor-paginated only. Set the page size with limit (max 1000), then follow pagination.next_cursor as ?cursor= until it comes back null.

There is no offset-based paging. per_page / page_size are accepted as aliases for limit. A position parameter that names the first page — page=1, offset=0, skip=0 — is accepted and ignored, and the response carries a Warning: 299 header telling you to move to cursors. Any other value (page=2, offset=500, …) returns 400 INVALID_PARAM: it cannot be honored, and silently ignoring it would re-serve the first page forever while has_more stayed true.

A page that returns exactly limit rows always yields a next_cursor, so when the row count divides evenly into your page size the final call returns an empty data array with a null cursor. That is normal termination, not an error — don't treat an empty page as a failure.

Cursors are stable under concurrent writes — a row inserted mid-sync won't cause the next page to skip a record. The cursor encodes (updated_at, id) and the server returns rows ordered the same way, so ties on updated_at are broken deterministically by id.

For nightly syncs, save the timestamp at which your job started (not finished) and use it as the next run's since. This guarantees no rows fall in the gap between your read and a row's next update.

Errors

Errors come back in a uniform envelope:

{
  "error": {
    "code": "INVALID_KEY",
    "message": "API key not recognized."
  }
}

Unknown parameters fail loudly

Any query parameter that isn't in the accepted list for that list endpoint (see What each endpoint accepts) returns 400 INVALID_PARAM naming it and listing the supported parameters, instead of being silently ignored. Typos and invented filter names surface immediately rather than returning unfiltered data that looks plausible. Recognized aliases are applied instead of rejected.

An offset position parameter with a non-first-page value (page=2, offset=500, skip=10) gets a 400 of its own, with a message pointing at cursor pagination; a first-page value is ignored with a Warning header instead. An out-of-vocabulary ?status= on /knocks or /leads is also a 400 INVALID_PARAM listing the valid statuses, rather than an empty 200. The same applies to a malformed date or timestamp, a repeated parameter, two spellings of the same filter, and a cursor that does not decode (400 INVALID_CURSOR).

Rate Limits

Several limiters stack, and they are not all keyed on your organization. The per-IP limiter is the one most integrations hit first, so pace against it.

Practical guidance: pace your integration against the 60 requests/minute per IP budget, and keep longer-window throughput inside the global 100 requests / 15 minutes per IP. Running from a shared egress IP (a NAT gateway, a CI runner pool) means other traffic from that IP spends the same budget. At limit=1000, 60 requests/minute is still 60,000 rows in a burst minute — ample for any nightly sync we've seen.

Rate-limit headers

Responses carry the draft-6 standard headers — no X- prefix:

• RateLimit-Limit — the window's budget
• RateLimit-Remaining — requests left in the window
• RateLimit-Reset — seconds until the window resets
• Retry-After — sent on a 429; wait at least this long before retrying

Endpoints

Returns metadata about your organization — name, tier, subscription status, member count, and your invite codes. Useful as a sanity check that your key resolves to the org you expect.

curl -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  https://app.solarknock.com/api/v1/reporting/org

Every member of your organization with their role, email, profile info, last login time, and closer status. One row per user.

Returned fields: id, name, email, role, is_closer, available_to_close, profile_picture_url, badge_photo_url, created_at, last_login_at, membership_status, joined_at, default_org_id.

Every knock pin in your organization — homeowner name, address, lat/lng, status, notes, disposition, follow-up date, the rep who knocked, and links to any lead or appointment that resulted. Each row includes actionsTaken (camelCase, like every row field on this endpoint) — a string array of actions the rep took at the door (price_estimate, proposal_given), independent of the disposition. Empty array when none were recorded.

Endpoint-specific filters:

• user_id=<uuid> — only this rep's knocks. This is the filter for the response field createdBy (parameters are snake_case, response fields are camelCase).
• status=<value> — e.g. ?status=set_appointment. Takes the internal status values: not_home, not_interested, new_lead, set_appointment, closed_deal, follow_up, no_decision_maker, renter, never_knock, failed_knock.
• knock_date_from=YYYY-MM-DD & knock_date_to=YYYY-MM-DD — calendar-day range against knock_date (device-local; see Dates & Time Zones), distinct from since/until, which target updated_at
• county_fips=<5-digit> — pins inside one US county

curl -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://app.solarknock.com/api/v1/reporting/knocks?since=2026-04-30T00:00:00Z&limit=1000"

Every lead in your organization except those created by the SitePilot sold-deal sync (source = 'sitepilot'), which are excluded — name, contact info, monthly bill, roof type, interest level, status, score, notes, system-size estimate, savings projection, and attachments. Each row includes actionsTaken (camelCase, like every row field on this endpoint) — a string array of actions recorded on the lead (price_estimate, proposal_given, qualified), independent of status. qualified moved from a lead status into an action: historical leads may still carry status: "qualified" and remain filterable, but new work records it here. Empty array when none were recorded.

Endpoint-specific filters:

• status=<value> — the complete lead status vocabulary is new, contacted, qualified, appointment_set, won, lost, canceled. There is no appointment lead status. A lead with status: "won" is a deal.
• user_id=<uuid> — only this rep's leads. This is the filter for the response field createdBy (parameters are snake_case, response fields are camelCase).
• created_from=YYYY-MM-DD & created_to=YYYY-MM-DD — calendar-day range against creation

The attachments field is a JSON array. Each attachment includes id, fileName, mimeType, size, uploadedAt, uploadedBy, and a download_url pointing at the attachment download endpoint below. The URL is permanent — its security comes from the same Bearer key, not the URL itself. Revoking a key stops that key from fetching these URLs; your other keys keep working.

Every appointment your team has set — date, time, type, status, the closer assigned, the setter who set it, and the lead/pin it relates to. Both Google Calendar event IDs are returned for reps who have calendar sync enabled.

Endpoint-specific filters:

• closer_id=<uuid> / setter_id=<uuid>
• status=<value> — pending, completed, cancelled, etc.
• date_from=YYYY-MM-DD & date_to=YYYY-MM-DD — appointment's own date

Pre-aggregated per-(user, date) counters: knock count, leads generated, appointments set, deals closed, hours worked, and the timestamps of each individual knock that day. Convenient for a quick rollup — but it is a derived table, not the source of truth.

Endpoint-specific filters:

• user_id=<uuid>
• date_from=YYYY-MM-DD & date_to=YYYY-MM-DD

One row per (user, day) where the user opened the SolarKnock app. Useful for "active reps" calculations and attendance analytics.

Every US county your organization has knocked in, with renter-data availability status and a count of knocks per county.

Streams the raw bytes of a lead attachment — power bills, drivers licenses, contract scans, photos. The :lead_id and :file_id values come from the download_url returned in each attachment object on the /leads endpoint.

Auth is the same Bearer key as every other reporting endpoint. The endpoint returns the file as an attachment download with the original filename and mime type preserved. Cross-org isolation is enforced — the lead must belong to the organization that owns the API key, otherwise you get a 404.

curl -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -o power_bill.pdf \
  https://app.solarknock.com/api/v1/reporting/attachments/f7a.../9b1...

Write Endpoints

Push knocks into SolarKnock from a third-party app (AI transcription, custom field tablet, voice-to-text dialer). One POST creates the knock and — when the disposition warrants — cascades into a lead and an appointment in a single round-trip. PATCH lets you update the disposition or notes on a knock you previously created (e.g. when an AI re-classifies after a follow-up call).

Auth, idempotency, rate limit

• Auth: same Bearer header as reads.
• Idempotency: set Idempotency-Key: <uuid> on every write. We store the key for 24h. Same key + same body → original 201 returned with meta.idempotent_replay: true. Same key + different body → 409 IDEMPOTENCY_KEY_REUSED.
• Rate limit (writes): 30 requests / minute / org — a separate budget from the read limiters, but the per-IP limits still apply on top. See Rate Limits.
• Body size cap: 50 KB. Larger requests get 413 PAYLOAD_TOO_LARGE.
• Address verification: server canonicalizes your address via the USPS-grade Smarty service. Lat/lng on the resulting knock is the verified canonical lat/lng (often a few meters more accurate than client GPS). County FIPS is stamped automatically.
• Auto-disable: if your integration produces ≥50 4xx responses in any rolling hour (or other suspicious patterns), the API auto-disables writes for your org. An admin must re-enable from the Profile panel after fixing the integration.

Create a knock. Optionally cascades into a lead (when disposition is Lead, Appointment, or maps to follow_up) and an appointment (when disposition is Appointment and appointment_datetime + closer_id are present).

Required body fields

Optional body fields

Disposition → internal status mapping

Power users: pass status directly to access internal-only states (follow_up, renter, no_decision_maker, never_knock, failed_knock). If both status and disposition are present, status wins.

Response (201 Created)

{
  "data": {
    "knock": { /* full knock_pins row */ },
    "lead": { /* lead row, or null */ },
    "appointment": { /* appointment row, or null */ }
  },
  "meta": {
    "org_id": "f7a...",
    "created_at": "2026-05-13T19:30:00Z",
    "source": "api",
    "assignee_created": false,
    "address_verified": true,
    "rdi": "Residential",
    "idempotent_replay": false
  }
}

Examples

curl -X POST "https://app.solarknock.com/api/v1/reporting/knocks" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 4f8c8a52-3e02-4a1f-91a3-c6e3b9f1b30c" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, Brooklyn NY 11201",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "disposition": "Not Home",
    "knock_timestamp": "2026-05-13T15:42:00Z",
    "user_email": "jose@sunrise-solar.com"
  }'

curl -X POST "https://app.solarknock.com/api/v1/reporting/knocks" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 9f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, Brooklyn NY 11201",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "disposition": "Appointment",
    "knock_timestamp": "2026-05-13T15:42:00Z",
    "user_email": "jose@sunrise-solar.com",
    "homeowner_name": "Jane Doe",
    "homeowner_phone": "+15551234567",
    "homeowner_email": "jane@example.com",
    "notes": "Strong interest. Currently paying $310/mo to Con Ed.",
    "electric_bill_amount": 310,
    "system_size_kw": 8.4,
    "roof_type": "asphalt",
    "actions_taken": ["price_estimate", "proposal_given"],
    "lead_actions_taken": ["price_estimate", "proposal_given", "qualified"],
    "appointment_datetime": "2026-05-15T18:30:00Z",
    "closer_id": "u_closer_abc",
    "meta": {
      "ai_transcript_id": "tr_abc123",
      "ai_confidence": 0.94
    }
  }'

Error codes (POST)

Partial update of an existing knock you created. Use this when the AI re-classifies after a follow-up call ("Not Home" → "Lead"), or to attach late-arriving notes / a refined bill amount.

Mutable: status or disposition, notes, disposition_notes, homeowner_name, homeowner_phone, homeowner_email, electric_bill_amount, actions_taken (replaces the array — send the full set), follow_up_date, meta (deep-merged onto existing).

Immutable: id, org, created_by, created_at, knock_date, latitude, longitude, daily_knock_number, source. Anything not in the mutable list is silently ignored.

curl -X PATCH "https://app.solarknock.com/api/v1/reporting/knocks/01H8X8X8X8..." \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "disposition": "Lead",
    "notes": "Came back at 7pm. Husband is now interested. Asked us to set an appointment Thursday.",
    "follow_up_date": "2026-05-16"
  }'

Photo attachments — coming soon

POST /knocks/:id/photos (door / roof / utility-bill photo upload) is on the roadmap for v2. Until then, photo attachments are only supported on leads via the in-app UI.

Lead Lifecycle & Commission

After a deal is sold it moves through financing, permitting, install and payout — usually tracked in someone else's system. These endpoints let that system write progress back onto the SolarKnock lead, and record who gets paid what.

Finding the lead

Most external systems know an address, not a SolarKnock lead id. This resolves one to the other, and it is a dry run — same 200/404/409 envelope as a write, with no side effects. Use it to check your matching before you start writing.

Pass either address (free-form, we parse it) or street + optionally city / zip. Add match=loose to widen.

How matching resolves

Every 404 and 409 on a write is a no-op. We never apply part of a batch and then fail.

Reading milestones

Returns all seven milestones every time, whether or not they have been set. A milestone is done when it has an actual_date.

Writing milestones

Send { "milestones": [ … ] }. Each entry takes milestone plus any of actual_date, target_date, comment, not_applicable, external_ref. Dates are YYYY-MM-DD. Omitted milestones are left alone — this is a patch, not a replace. Setting actual_date: null clears it.

A bad entry does not discard the good ones. Every entry comes back in meta.results with applied: true, or applied: false plus an error code (UNKNOWN_MILESTONE, INVALID_DATE). The response body is the full current state of all seven.

curl -X PATCH -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  https://app.solarknock.com/api/v1/reporting/leads/by-address/milestones \
  -d '{
    "street": "900 Writeback Way", "city": "Alphaville",
    "milestones": [
      { "milestone": "lender_approved",   "actual_date": "2026-07-20", "external_ref": "lender:CASE-1" },
      { "milestone": "project_scheduled", "target_date": "2026-09-15" }
    ]
  }'

Commission

How commission is stored

Commission attaches to the lead, and it is per person — not one number per deal. Each person on a deal has up to two rows:

• kind: "projected" — what they are expected to earn.
• kind: "paid" — what they were actually paid.

A row is identified by (lead, user, kind). Someone who is both the setter and the closer on a deal therefore has one projected row and one paid row, not two of each. The two kinds are independent — writing paid never disturbs projected.

The role field on a row (setter / closer) is a display label only. It is filled in when that person is the lead's setter or closer, and is null otherwise. It never affects which row is which.

Reading commission

Returns every split on the lead plus totals.projected and totals.paid. The by-address form accepts the same parameters and follows the same resolution rules as /leads/by-address.

Your API key authenticates an organization, so nothing is hidden here — you get every person's amounts. (The SolarKnock mobile app masks other people's amounts from an individual rep; that is a UI behaviour and does not apply to this API.)

{
  "data": {
    "lead_id": "a1b2c3…",
    // Every split on the lead, both kinds, ordered by kind then name.
    "splits": [
      { "id": "2a1ff167…",
        "user_id": "u1…", "name": "Sam Kimball", "email": "sam@acme.com",
        "role": "setter", "kind": "paid",
        "percent": null, "amount": null, "notes": null,
        "updated_at": "2026-08-14 18:22:10.477737+00" },
      { "id": "3ec82ac9…",
        "user_id": "u1…", "name": "Sam Kimball", "email": "sam@acme.com",
        "role": "setter", "kind": "projected",
        "percent": 40, "amount": 1200, "notes": null,
        "updated_at": "2026-08-14 18:22:10.574623+00" },
      { "id": "1ae982ba…",
        "user_id": "u2…", "name": "Landon Davenport", "email": "landon@acme.com",
        "role": "closer", "kind": "projected",
        "percent": 60, "amount": 1800, "notes": null,
        "updated_at": "2026-08-14 18:22:11.001204+00" }
    ],
    // Sum of `amount` per kind. Nulls count as zero.
    "totals": { "projected": 3000, "paid": 0 }
  },
  "meta": {}
}

Writing commission

Send { "splits": [ … ] }. Each entry needs a person and a kind, plus whichever values you are setting.

Omitted fields are left as they were — send { "amount": 1100 } and an existing percent and notes survive. Send null to clear a value. You must supply at least one of percent, amount or notes, or the entry comes back NOTHING_TO_APPLY.

Partial batches apply. Each entry is reported in meta.results; a rejected entry never discards the accepted ones.

curl -X PATCH -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  https://app.solarknock.com/api/v1/reporting/leads/a1b2c3…/commission \
  -d '{
    "splits": [
      { "user_email": "setter@acme.com", "kind": "projected", "percent": 40, "amount": 1200 },
      { "user_email": "closer@acme.com", "kind": "projected", "percent": 60, "amount": 1800 }
    ]
  }'

# 1. the amounts
curl -X PATCH -H "Authorization: Bearer sk_live_xxx" -H "Content-Type: application/json" \
  https://app.solarknock.com/api/v1/reporting/leads/by-address/commission \
  -d '{
    "street": "900 Writeback Way", "city": "Alphaville",
    "splits": [
      { "user_email": "setter@acme.com", "kind": "paid", "amount": 1150 },
      { "user_email": "closer@acme.com", "kind": "paid", "amount": 1800 },
      { "user_email": "manager@acme.com", "kind": "paid", "amount": 250, "notes": "override" }
    ]
  }'

# 2. the date it was paid — that lives on the commission_paid milestone
curl -X PATCH -H "Authorization: Bearer sk_live_xxx" -H "Content-Type: application/json" \
  https://app.solarknock.com/api/v1/reporting/leads/by-address/milestones \
  -d '{
    "street": "900 Writeback Way", "city": "Alphaville",
    "milestones": [ { "milestone": "commission_paid", "actual_date": "2026-08-14" } ]
  }'

Recipe: Full Warehouse Pull

Run once when you set up the integration. Pulls every row from every endpoint into your warehouse.

const API_KEY = process.env.SOLARKNOCK_KEY;
const BASE = "https://app.solarknock.com/api/v1/reporting";

async function pullAll(endpoint) {
  let cursor = null, all = [];
  do {
    const url = `${BASE}/${endpoint}?limit=1000${cursor ? `&cursor=${cursor}` : ""}`;
    const resp = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` }});
    const body = await resp.json();
    all.push(...body.data);
    cursor = body.pagination.next_cursor;
  } while (cursor);
  return all;
}

for (const ep of ["users", "knocks", "leads", "appointments", "daily-stats"]) {
  const rows = await pullAll(ep);
  // upsert into your warehouse / CSV / etc
  console.log(`${ep}: ${rows.length} rows`);
}

Recipe: Nightly Incremental Sync

Save the timestamp at which the job started, use it as the next run's since. The diff is small, the cursor pages through it, and you never miss a row even if updates land mid-sync.

import os, requests, datetime as dt
from pathlib import Path

API_KEY = os.environ["SOLARKNOCK_KEY"]
STATE   = Path("last_run.txt")
BASE    = "https://app.solarknock.com/api/v1/reporting"

since = STATE.read_text().strip() if STATE.exists() else "1970-01-01T00:00:00Z"
started = dt.datetime.utcnow().isoformat() + "Z"

def pull(endpoint):
    cursor = None
    while True:
        params = {"since": since, "limit": 1000}
        if cursor: params["cursor"] = cursor
        r = requests.get(f"{BASE}/{endpoint}", params=params,
                         headers={"Authorization": f"Bearer {API_KEY}"})
        body = r.json()
        yield from body["data"]
        cursor = body["pagination"]["next_cursor"]
        if not cursor: break

# since/until are only accepted on these three endpoints. /daily-stats has no
# updated_at filter (window it with date_from/date_to) and /users has none at all.
for endpoint in ["knocks", "leads", "appointments"]:
    for row in pull(endpoint):
        if row.get("deletedAt"):
            # delete(endpoint, row["id"]) — tombstone, drop it from the warehouse
            continue
        # upsert(endpoint, row) — keyed on row["id"], NEVER append
        # day-bucket knocks on row["knockDate"], never on today's date
        pass

STATE.write_text(started)  # save for next run

Recipe: Connect to Your BI Tool

Most BI tools (Looker, Metabase, Tableau, Hex, Mode) can hit a paginated REST endpoint directly, but they're happiest with a flat table they own. The pattern that scales:

1. Stand up a small daily job (Airflow, GitHub Actions, cron) that runs the Python recipe above.
2. Land the rows in Postgres / Snowflake / BigQuery / DuckDB / a parquet file in S3.
3. Point your BI tool at the warehouse, not at this API directly.

This way your dashboards stay fast (no API round-trips per query), and you can join SolarKnock data with your own CRM, payroll, and financial data.