Build approved senior-care integrations with audited APIs and signed webhooks.

/api/v1/partner/providers

Partner provider directory API requiring providers:read scope

/api/v1/partner/providers/{id}

Partner provider detail API requiring providers:read scope with source provenance metadata

/api/v1/partner/providers/{id}/visibility

Partner provider visibility readiness API requiring providers:read scope with aggregate scores

/api/v1/partner/providers/{id}/reputation-readiness

Partner provider reputation readiness API requiring reviews:read scope with aggregate review, campaign, and sentiment health

/api/v1/partner/providers/{id}/review-summary

Partner provider review summary API requiring reviews:read scope with aggregate rating, source, and sentiment metrics

/api/v1/partner/providers/{id}/event-summary

Partner provider event summary API requiring events:read scope with aggregate RSVP, promotion, and ad metrics

/api/v1/partner/providers/{id}/community-summary

Partner provider community summary API requiring community:read scope with aggregate published-post and sponsorship metrics

/api/v1/partner/providers/{id}/ad-summary

Partner provider ad summary API requiring ads:read scope with aggregate delivery, placement, and health metrics

/api/v1/partner/providers/{id}/campaign-summary

Partner provider campaign summary API requiring campaigns:read scope with aggregate campaign, asset, and metric rollups

/api/v1/partner/providers/{id}/newsletter-summary

Partner provider newsletter summary API requiring newsroom:read scope with aggregate delivery and performance metrics

/api/v1/partner/events

Partner events API requiring events:read scope

/api/v1/partner/events/{id}/analytics

Partner event analytics API requiring events:read scope with aggregate RSVP and promotion metrics

/api/v1/partner/reviews

Partner published reviews API requiring reviews:read scope with privacy-safe reviewer fields

/api/v1/partner/community/posts

Partner published community posts API requiring community:read scope with pagination and sponsorship disclosures

/api/v1/partner/newsroom/articles

Partner published newsroom articles API requiring newsroom:read scope with attribution and preview-only body metadata

/api/v1/partner/newsroom/newsletters

Partner public newsletter editions API requiring newsroom:read scope with recipient-safe metadata

/api/v1/partner/newsroom/performance

Partner aggregated newsroom performance API requiring newsroom:read scope without raw metric payloads

/api/v1/partner/newsroom/readiness

Partner newsroom syndication readiness API requiring newsroom:read scope with aggregate blocker evidence

/api/v1/partner/newsroom/sources

Partner approved newsroom source registry API requiring newsroom:read scope with attribution metadata

/api/v1/partner/ads/placements

Partner ad placement inventory API requiring ads:read scope with disclosure and optional delivery preview metadata

/api/v1/partner/aggregation/readiness

Partner aggregation readiness API requiring providers:read scope with aggregate source, import, crawler, and quality health

/api/v1/partner/campaigns

Partner published campaigns API requiring campaigns:read scope with optional provider metrics rollup

/api/v1/partner/claims

Partner provider claim/data-correction submission API requiring claims:write scope with verification checklist evidence

/api/v1/partner/claims/{id}

Partner provider claim status API requiring claims:write scope and matching claimant email

/api/v1/partner/claims/{id}/verification-evidence

Partner provider claim evidence submission API requiring claims:write scope, claimant email match, and attestation

/api/v1/partner/usage

Partner-scoped API usage summary, retention policy, or CSV export requiring usage:read scope

/api/v1/partner/onboarding-checklist

Return the partner sandbox onboarding checklist with scopes, evidence, and production promotion blockers

/api/v1/partner/changelog

Return partner API version changelog, deprecation policy, migration notes, and planned release signals

/api/v1/partner/sdk-package-plan

Return webhook SDK package publishing plan, security controls, release gates, and owner blockers

/api/v1/partner/sandbox-evidence

Return JSON or CSV partner sandbox evidence bundle for promotion review

/api/v1/partner/response-envelope

Return partner response envelope version, headers, paths, and migration rules

/api/v1/partner/response-pagination

Return partner response pagination parameters, meta shape, and traversal rules

/api/v1/partner/pagination-evaluation

Return JSON or CSV partner cursor pagination evaluation, offset limits, migration gates, and endpoint candidates

/api/v1/partner/webhooks/signing-guide

Return webhook signing headers, HMAC verification steps, event list, and deterministic sample payload

/api/v1/partner/webhooks/verify

Verify a webhook payload signature for an owned subscription requiring webhooks:write scope

/api/v1/partner/developer-docs

Return partner developer documentation, SDK examples, OpenAPI endpoints, and webhook signing contracts

/api/v1/partner/pagination-volume-evidence

Return JSON or CSV partner cursor pagination production-volume evidence and threshold blockers

/api/v1/partner/sdk-publish-readiness

Return JSON or CSV webhook SDK registry publish readiness, owner approvals, and smoke evidence blockers

Verify a webhook signature in Node.js

import crypto from "node:crypto";

const secret = "whsec_example_do_not_use";
const timestamp = "1778792400";
const rawBody = "{\"id\":\"webhook-delivery-example\",\"eventType\":\"provider.updated\",\"subjectId\":\"provider-example\",\"payload\":{\"providerId\":\"provider-example\",\"status\":\"updated\"},\"createdAt\":\"2026-05-14T21:00:00.000Z\"}";
const signature = "t=1778792400,v1=c6712f63cdc2c4dc3c0df540b951905799fab2b40a2a0f61570461a0d07166c2";
const expectedDigest = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const suppliedDigest = signature.split("v1=")[1];
const valid = crypto.timingSafeEqual(Buffer.from(expectedDigest), Buffer.from(suppliedDigest));

Verify a webhook signature in Python

import hmac
import hashlib

secret = "whsec_example_do_not_use"
timestamp = "1778792400"
raw_body = "{\"id\":\"webhook-delivery-example\",\"eventType\":\"provider.updated\",\"subjectId\":\"provider-example\",\"payload\":{\"providerId\":\"provider-example\",\"status\":\"updated\"},\"createdAt\":\"2026-05-14T21:00:00.000Z\"}"
signature = "t=1778792400,v1=c6712f63cdc2c4dc3c0df540b951905799fab2b40a2a0f61570461a0d07166c2"
expected_digest = hmac.new(secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest()
supplied_digest = signature.split("v1=")[1]
valid = hmac.compare_digest(expected_digest, supplied_digest)

Call the partner providers endpoint

curl -sS \
  -H "x-senior-guru-api-key: $SENIOR_GURU_API_KEY" \
  -H "accept: application/json" \
  https://theseniorguru.vercel.app/api/v1/partner/providers

Create a sandbox API client with least-privilege scopes

POST /api/v1/admin/api-clients

Client has sandboxMode=true, status=active, rate limit, owner type, and approved scopes.

Do not issue live-mode clients until partner business owner, data use, and webhook purpose are approved.

Mint one sandbox key and store the secret outside The Senior Guru

POST /api/v1/admin/api-clients/{id}/keys

Key preview is visible in admin records and the full secret was copied once into the partner vault.

Lost secrets must be revoked and reissued; backend never exposes stored key material.

Call provider inventory from the partner environment

GET /api/v1/partner/providers

Response includes provider records and rate-limit headers with x-senior-guru-sandbox=true.

403 responses mean the key is missing providers:read scope or the client is paused/revoked.

Call provider detail by id or slug with source provenance

GET /api/v1/partner/providers/{id}

Response includes one approved provider record, source provenance, lookup metadata, partner envelope headers, and excludes internal admin notes or claim verification evidence.

Do not hydrate partner provider profiles from non-approved statuses or from internal claim verification evidence.

Call provider visibility readiness without internal action links

GET /api/v1/partner/providers/{id}/visibility

Response includes aggregate provider readiness scores, metrics, missing public profile fields, and next-best-action labels without entitlement keys, internal URLs, or claim evidence.

Do not use provider readiness evidence for partner ranking when internal entitlements, audit records, or claim verification evidence are required by the partner workflow.

Call provider reputation readiness without reviewer identity

GET /api/v1/partner/providers/{id}/reputation-readiness

Response includes aggregate review, campaign, sentiment, blocker, and next-action readiness with partner envelope headers and no reviewer emails, request recipients, moderation notes, or internal action URLs.

Do not use reputation readiness externally when the partner workflow requires raw reviewer identity, moderation evidence, or recipient-level request records.

Call provider review summary without raw review text

GET /api/v1/partner/providers/{id}/review-summary

Response includes aggregate published-review count, rating distribution, source counts, sentiment totals, partner envelope headers, and no reviewer names, emails, body text, moderation status, or recipient details.

Do not use review summary output as a raw testimonial feed; use the published reviews endpoint when approved display attribution is required.

Call provider event summary without attendee PII

GET /api/v1/partner/providers/{id}/event-summary

Response includes provider-scoped event counts, RSVP totals, promotion totals, ad metrics, public event references, partner envelope headers, and no attendee names, emails, phones, consent payloads, or per-RSVP rows.

Do not share provider event performance externally if the partner workflow requires attendee-level consent evidence or raw RSVP records.

Call provider community summary without author identity

GET /api/v1/partner/providers/{id}/community-summary

Response includes provider-scoped published post counts, sponsorship disclosure totals, post type/location distribution, public post references, partner envelope headers, and no author names, body text, comments, member identity, or moderation status.

Do not use community summary output as a raw community feed; use the published community posts endpoint when approved post display rules are required.

Call provider ad summary without raw creative payloads

GET /api/v1/partner/providers/{id}/ad-summary

Response includes provider-scoped aggregate delivery totals, placement rollups, ad health, recommendations, partner envelope headers, and no raw creative payloads, destination URLs, visitor context, request IDs, or row-level impression/click records.

Do not use ad summary output for creative rendering; use approved ad placement inventory and preserve disclosure labels before rendering sponsored placements.

Call provider campaign summary without raw asset payloads

GET /api/v1/partner/providers/{id}/campaign-summary

Response includes provider-scoped campaign totals, asset approval totals, metric rollups, type/status/channel distributions, public campaign references, partner envelope headers, and no campaign audience payloads, asset bodies, asset payloads, metric payloads, or row-level metric records.

Do not mirror campaign assets or audience rules from summary output; use approved campaign inventory and owner-reviewed channel rules before external display.

Call event inventory and confirm date/location handling

GET /api/v1/partner/events

Response includes event records with community-safe metadata for sandbox validation.

Do not mirror events publicly until partner display rules and sponsorship disclosures are reviewed.

Call aggregate event analytics without attendee PII

GET /api/v1/partner/events/{id}/analytics

Response includes aggregate RSVP, promotion, and ad metrics with partner envelope headers and no attendee names, emails, phones, or consent payloads.

Do not share event performance externally if attendee PII, consent payloads, or provider-only notes are required by the partner workflow.

Call published review inventory without reviewer email exposure

GET /api/v1/partner/reviews

Response includes only published reviews, provider context, pagination metadata, and no reviewer email field.

Do not syndicate reviews until partner display rules, attribution, and moderation status handling are approved.

Call published community posts with sponsorship disclosures

GET /api/v1/partner/community/posts

Response includes only published community posts, optional location/topic filters, pagination metadata, and disclosure labels for sponsored posts.

Do not mirror community content until partner moderation display rules and sponsored-content disclosure handling are approved.

Call published newsroom articles with attribution metadata

GET /api/v1/partner/newsroom/articles

Response includes only published articles, preview body text, source links, topic/audience filters, pagination metadata, and partner envelope headers.

Do not syndicate editorial content unless attribution, preview-only body display, and partner content-use approval are preserved.

Call public newsletter editions without recipient details

GET /api/v1/partner/newsroom/newsletters

Response includes approved, scheduled, or sent newsletter metadata, linked article references, pagination metadata, and no recipient or delivery-attempt records.

Do not syndicate newsletter editions unless attribution, unsubscribe expectations, and recipient privacy boundaries are preserved.

Call provider newsletter summary without recipient details

GET /api/v1/partner/providers/{id}/newsletter-summary

Response includes provider-scoped newsletter delivery and performance rollups, blocker evidence, and no recipient identities, delivery payload previews, delivery attempt IDs, audience segments, or raw metric payloads.

Do not use provider newsletter analytics unless aggregate-only reporting and recipient privacy boundaries are preserved.

Call aggregated newsroom performance without raw payloads

GET /api/v1/partner/newsroom/performance

Response includes aggregate totals, channel rollups, top article/newsletter rows, partner envelope metadata, and no raw metric payloads or recipient records.

Do not use partner content performance evidence unless aggregation-only reporting and recipient privacy boundaries are preserved.

Call newsroom syndication readiness before mirroring content

GET /api/v1/partner/newsroom/readiness

Response includes aggregate source, article, derivative, and blocker summaries with no draft bodies, source item bodies, or admin review notes.

Do not enable partner syndication when readiness status is blocked or action_required without partner content-use and editorial approval.

Call approved newsroom source attribution metadata

GET /api/v1/partner/newsroom/sources

Response includes only approved source records, attribution notes, pagination metadata, and excludes pending, blocked, legal-review, and raw source item bodies.

Do not attribute or mirror newsroom content from sources that are pending, blocked, or awaiting legal review.

Call ad placement inventory with disclosure metadata

GET /api/v1/partner/ads/placements

Response includes active placements, surfaces, disclosure labels, pagination metadata, and optional delivery preview data when includeCreatives=true.

Do not render paid placements unless the partner UI preserves disclosure labels and separates organic ranking from sponsored placement.

Call aggregation readiness before relying on provider inventory freshness

GET /api/v1/partner/aggregation/readiness

Response includes aggregate source, import, crawler, launch target, and quality health with no source IDs, base URLs, terms notes, queue rows, import batches, crawl jobs, or quality flag rows.

Do not market inventory freshness or launch coverage claims unless aggregate readiness is ready or action_required blockers are accepted.

Call published campaign inventory with optional metrics

GET /api/v1/partner/campaigns

Response includes published non-blocked campaigns, provider/type/status filters, pagination metadata, and optional metrics when includeMetrics=true.

Do not mirror campaign content until partner campaign purpose, channel rules, consent boundaries, and attribution are approved.

Submit a provider claim or data correction request

POST /api/v1/partner/claims

Response includes the created provider claim, verification checklist, next action, partner envelope metadata, and API audit evidence.

Do not submit third-party correction claims without claimant authority, provider identity evidence, and partner data-use approval.

Poll claim status with claimant email verification

GET /api/v1/partner/claims/{id}?claimantEmail={email}

Response includes the claim, checklist, next action, and partner envelope metadata only when the claimant email matches.

Do not expose claim status in partner systems unless the claimant email match and partner data-use approval are both preserved.

Submit provider claim verification evidence with claimant match

POST /api/v1/partner/claims/{id}/verification-evidence

Response includes safe verification attempt status and refreshed claim checklist after claimantEmail match and attestation acceptance; raw evidence, attempt IDs, verification targets, and policy decisions are excluded.

Do not submit or display claim evidence unless the claimant email matches the original claim and the claimant has accepted the attestation.

Review JSON and CSV usage evidence

GET /api/v1/partner/usage?format=csv

Usage export shows allowed, blocked, and rate-limited calls for partner operations review.

Missing usage evidence blocks production promotion because launch operations cannot audit partner access.

Register the sandbox webhook endpoint

POST /api/v1/admin/webhook-subscriptions

Subscription uses HTTPS, approved event types, active status, and a one-time signing secret.

HTTP targets, unsupported events, and missing signing-secret custody block subscription approval.

Verify webhook signatures against the deterministic sample

POST /api/v1/partner/webhooks/verify

Partner code validates x-senior-guru-signature using HMAC-SHA256 over timestamp.rawBody.

Parsing JSON before verifying the raw body can invalidate signatures and blocks production approval.

Review sandbox evidence before live promotion

GET /api/v1/admin/api-usage-analytics

Admin usage analytics, webhook delivery evidence, link-health, and OpenAPI coverage are reviewed.

Production mode remains blocked until owner approves partner purpose, scopes, rate limits, and webhook events.

0.1.0

Initial governed partner API foundation for sandbox provider/event reads, usage evidence, webhook verification, developer docs, and onboarding readiness.

Scoped partner API key authentication with rate-limit headers and sandbox-mode response metadata. Provider and event read endpoints for approved partner integrations. Partner usage analytics with JSON and CSV evidence export. Webhook signing guide, signature verification endpoint, replay evidence export, and SDK examples. Sandbox onboarding checklist with production promotion blockers and evidence signals.

Use x-senior-guru-api-key for all partner calls. Treat all 0.x endpoints as pre-1.0 and verify OpenAPI metadata before production promotion. Keep sandbox clients in sandboxMode=true until owner approval records partner purpose, scopes, rate limits, and webhook events.

0.2.0

Planned partner evidence release for sandbox evidence export, versioned response envelopes, and SDK package publishing guidance.

Sandbox evidence bundle export for provider, events, usage, webhook, and link-health checks. Explicit response envelope version metadata for partner routes. Package publishing plan for signed webhook verification helpers.

No breaking changes are planned for 0.2.0. Partners should begin storing usage and webhook evidence ids so evidence bundles can reconcile prior sandbox runs.

@theseniorguru/webhooks

verifySeniorGuruWebhookSignature

Verify x-senior-guru-signature using HMAC-SHA256 and timing-safe digest comparison. Enforce timestamp tolerance before application JSON parsing. Return typed verification results with failure reasons for audit logging.

Publish only after npm organization ownership, package provenance, 2FA, README review, and signed release workflow are approved.

theseniorguru-webhooks

verify_senior_guru_webhook_signature

Verify x-senior-guru-signature using hmac.compare_digest. Keep raw-body verification separate from framework JSON parsing. Expose deterministic sample tests matching the live signing-guide payload.

Publish only after PyPI ownership, trusted publishing, README review, and signed release workflow are approved.