providers lane
Developers / API referenceAPI 1.0.0

BUILD WITH PROVIDERS LANE

Providers Lane API documentation

Use source-linked specialty and care-category information in your application, or prepare a provider-reviewed profile draft. Start with the public API; no API key is needed for educational reads or preparation.

Make your first request

Base URL: https://providerslane.com. Use HTTPS and the non-www address. Do not attach Authorization, account cookies, OTPs, passwords or patient details to public calls.

Shell
curl --fail-with-body --silent --show-error \
  https://providerslane.com/v1/knowledge/catalog

Read each specialty’s slug and guideAvailable. A false availability flag means a full guide is not published, not that the profession is invalid.

TypeScript
const response = await fetch('https://providerslane.com/v1/knowledge/guides/psychology', {
  headers: {Accept: 'application/json'},
  signal: AbortSignal.timeout(10000)
});
const body: unknown = await response.json();
if (!response.ok) throw new Error('Request failed: ' + response.status);
const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === 'object' && value !== null && !Array.isArray(value);
if (!isRecord(body) || !isRecord(body.data) || !isRecord(body.data.summary)) {
  throw new Error('Unexpected guide response');
}
console.log(body.data.title, body.data.summary.text);
// Preserve body.data.sources and body.data.review when presenting the content.

This TypeScript example is for a server or command-line runtime. Cross-origin browser requests are not enabled. Use your own backend; do not bypass Origin checks. A successful HTTP response is not a verification or publication receipt.

Endpoint reference

A compact reference to the live public contract. Each operation below comes from the OpenAPI specification.

Endpoint
GET /v1/knowledge/care-categories

List care categories and source-checked guide availability

Endpoint
GET /v1/knowledge/care-categories/{category}

Read a source-linked care-category guide

Endpoint
GET /v1/knowledge/care-categories/{category}.md

Read a care-category guide as Markdown

Endpoint
POST /v1/knowledge/care-search

Retrieve source-linked care-category passages

Endpoint
GET /v1/knowledge/catalog

List specialty labels and care categories

Endpoint
GET /v1/knowledge/specialties/{specialty}

Read a specialty definition

Endpoint
GET /v1/knowledge/guides/{specialty}

Read a full source-linked guide

Endpoint
GET /v1/knowledge/guides/{specialty}.md

Read the same guide as Markdown

Endpoint
POST /v1/knowledge/search

Retrieve source-linked answer passages

Endpoint
POST /v1/knowledge/compare

Compare specialty information without medical recommendations

Endpoint
GET /v1/provider-onboarding/schema

Read the portable private-profile draft schema

Endpoint
POST /v1/provider-onboarding/prepare

Prepare a draft packet for human review; does not save a profile

GET resources also support HEAD. Public POST requests require uncompressed application/json, no query parameters, and a body no larger than 16 KiB. Portable draft packets are limited to 8 KiB. The schema rejects undocumented fields.

Read the same guide in four formats

All representations use the same eligible content record. They carry the original text, references, content version, meaningful dates and review limitations.

FormatExample
HTML/specialties/psychology
JSON/v1/knowledge/guides/psychology
Markdown/v1/knowledge/guides/psychology.md
MCPget_specialty_guide with {"specialty":"psychology"}
FieldMeaning
apiVersionPublic API contract version.
kindType of result, such as specialty_guide or answer_passages.
scopepublic_education: not a private provider-account response.
contentRevisionHash identifying the current public catalog and eligible guide corpus.
data.versionVersion of this individual guide.
data.summarySummary text with its references.
data.sectionsSections, canonical fragment links, paragraphs, sources and preparation questions.
data.questionsPublished questions and answers with references.
data.reviewReview type, source-check date, attribution and explicit clinician-review limitation.

Source checking is not clinician review, endorsement by a source organization or verification of a provider. Preserve data.review; do not turn it into a “medically verified” badge.

Care-category guides

Care categories organize general navigation questions; they are not diagnoses or provider credentials. Read GET /v1/knowledge/care-categories for availability. Only reviewed, published guides are returned.

Shell
curl --fail-with-body --silent --show-error \
  https://providerslane.com/v1/knowledge/care-categories/primary-care

The canonical HTML guide is /care/primary-care. Append .md to the JSON guide URL for Markdown. The knowledge MCP exposes list_care_categories, get_care_category_guide and search_care_category_answers, plus published category-guide resources.

Shell
curl --fail-with-body --silent --show-error \
  https://providerslane.com/v1/knowledge/care-search \
  -H 'Content-Type: application/json' \
  --data '{"question":"What should I ask a primary care practice?","category":"primary-care","limit":3}'

Category search retrieves published passages and preserves their references and review limits. It does not generate a diagnosis, rank clinicians or offer personalized care advice. An unavailable guide or empty result is not proof that a service does not exist. Do not send patient details.

Prepare a provider-reviewed profile

Read GET /v1/provider-onboarding/schema before preparing data. The example is fictional and contains no private contacts or account-access secrets.

Shell
curl --fail-with-body --silent --show-error \
  https://providerslane.com/v1/provider-onboarding/prepare \
  -H 'Content-Type: application/json' \
  --data '{"profile":{"name":"Example Provider","specialty":"psychology","bio":"Fictional example for testing profile preparation.","visit_type":"video","languages":"English"}}'

The response contains data.packet, data.missingFields and data.readyForHumanReview. Preparation returns created: false, stored: false, verified: false and published: false. Validation does not establish that submitted professional claims are true.

The provider signs into their existing authorized workspace, completes required private details, opens /provider/agent-import, reviews the proposed changes and explicitly saves. Copy only data.packet, not the full response envelope. Individual registration is available through the provider signup flow. Organization integrations use the separate roster flow below.

Packets exclude private email/phone, NPI, ownership assignments, roles, verification or publication status, signatures and consent. Omitted optional fields preserve current values; explicit empty optional values clear them. A free-text insurance note does not replace structured accepted-plan records. Never give an agent your preview password, session cookie or OTP.

Connect a compatible MCP client

Prefer a protocol client? Open the MCP connection guide for the dedicated setup reference.

Knowledge: https://providerslane.com/mcp/knowledge. Preparation: https://providerslane.com/mcp/provider-onboarding. Both are stateless Streamable HTTP services for public information or preparation; neither accepts bearer credentials.

TypeScript
import {Client, StreamableHTTPClientTransport} from '@modelcontextprotocol/client';
const client = new Client({name: 'my-directory-client', version: '1.0.0'});
try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL('https://providerslane.com/mcp/knowledge')
  ));
  const result = await client.callTool({
    name: 'get_specialty_guide', arguments: {specialty: 'psychology'}
  });
  if (result.isError) throw new Error('MCP tool failed');
  console.log(result.structuredContent?.data);
} finally {
  await client.close();
}

The example follows the project’s pinned split client package. Pin and test your chosen client version; not every commercial assistant has been tested. Knowledge guides are also discoverable as MCP resources. Follow Content-Type: supported clients may receive JSON or finite SSE results.

Knowledge toolPurpose
list_medical_specialtiesList professional specialty labels, care categories and which source-checked guides are available. Catalog descriptions are not provider credentials.
get_medical_specialtyRead one professional specialty definition and related care categories; identifies whether a fuller guide is available.
get_specialty_guideGet the full published specialty guide with source-linked paragraphs, FAQs, version and explicit review limits. Missing/unpublished guides return an error.
search_specialty_answersRetrieve relevant passages for a general question about professions, credentials or choosing care. Returns sources, not a generated diagnosis or treatment recommendation. Do not supply patient details.
compare_medical_specialtiesCompare two to four professional specialties using their public summaries and sources. No clinician ranking or personal medical recommendation.
list_care_categoriesList care categories and available source-checked category guides. These are educational categories, not provider credentials.
get_care_category_guideRead a complete published care-category guide with source references, meaningful dates and explicit review limitations.
search_care_category_answersRetrieve original passages for a general question about care categories and professional roles. Not diagnosis, treatment or provider ranking.
Preparation toolPurpose
get_provider_profile_schemaGet the versioned packet format, allowed professional fields and required human steps. No login secrets, contact data, NPI or signatures belong in an agent packet.
prepare_provider_profileValidate and return a portable provider draft for authenticated human review. Does not store data, create an account, save a profile, claim ownership, sign consent, verify credentials or publish.

Opening an MCP endpoint in a browser issues GET and returns 405 with Allow: POST. That is expected; it is not a successful MCP session test. Use a protocol client for initialization, discovery and tool calls.

Handle errors and retries

REST errors use a structured error object. Example:

JSON
{
  "error": {
    "code": "guide_not_available",
    "message": "A published source-checked guide is not available for this specialty."
  }
}
HTTP statusWhat to do
400Correct malformed JSON or unsupported POST query parameters.
403Remove credentials from public-only calls or use an allowed Origin. Do not bypass controls.
404Check the catalog: the specialty or published guide may be unavailable.
405Use the documented method and inspect Allow.
408The request-body deadline expired.
413Reduce the public JSON body below 16 KiB or the draft packet below 8 KiB.
415Send uncompressed application/json.
422Correct field names, values, slugs, lengths or requested limits.
429Honor Retry-After and use bounded backoff with jitter.
500Use bounded retries; do not treat an error as a saved profile.

MCP clients should also inspect protocol errors and a tool result’s isError; a successful transport response alone does not mean the tool succeeded. Do not repeatedly retry invalid input. Retrying a public read or stateless preparation does not create duplicate profiles. The request budget is instance-local load protection, not a guaranteed distributed quota or SLA.

Individual delegated private-draft access: not deployed

No public draft-write endpoint is enabled for individual provider accounts. Keep anonymous preparation separate from authenticated organization-managed roster writes. Do not supply a provider password, OTP or session cookie to emulate API authorization. Browse approved source-reported listings at Find care.

Organization-managed provider rosters

An authorized representative starts at Organization onboarding, confirms their email and signs the accuracy and publication agreement. Staff checks organization authority before integrations can be created. This route does not require each provider to create an account, take a selfie or submit identity photos.

Organization attestations do not independently verify identity, licensure or credentials. Published profiles identify the supplying organization. Existing claimed or imported listings require an ownership review; an API cannot take them over.

Authentication

Use server-side OAuth client credentials at https://providerslane.com/oauth/organizations/token. Both client_secret_basic and client_secret_post are supported. Set grant_type=client_credentials and resource=https://providerslane.com/mcp/organizations. Access tokens expire after one hour. Roster scopes are roster:read, roster:write and roster:publish. Receiver-management credentials explicitly opt into webhooks:manage; this does not grant roster access. Keep secrets in your server secret manager; never send provider passwords, OTPs or session cookies.

MCP endpoint: https://providerslane.com/mcp/organizations. Use a client supporting the OAuth client-credentials extension, or obtain a token on your backend and send it as a Bearer token. Client support varies. Interactive authorization-code login and anonymous writes are unavailable. Metadata: /.well-known/oauth-protected-resource/mcp/organizations and /.well-known/oauth-authorization-server.

Import and update

  1. Read the schema and professional catalogs. Use providerslane.professional-profile.v2; it supports multiple professions, specialties and licenses.
  2. Validate a batch of up to 50 providers. Each row needs external_provider_id, expected_revision (0 for new records), authority_reference and profile. The envelope includes schema_version and your source_version.
  3. Inspect every row result, then commit the returned job_id and snapshot. Only valid rows are staged; duplicate identifiers invalidate the batch.
  4. Staff reviews new providers and material professional changes. Once enabled for the organization, routine updates to published profiles can proceed without another staff review.
  5. Publish that exact committed snapshot. Staging an edit preserves the previous public version until publication succeeds.

REST base: /v2/organizations/{organization_id}. Every request requires a Bearer token belonging to that organization. Write requests require a unique Idempotency-Key of 16–100 letters, numbers, underscores, periods or hyphens. Retry the same operation with the same key and payload; use a new key for a different operation. JSON bodies are limited to 1 MiB.

REST method and pathMCP tool
GET /providers?limit=50list_organization_providers
GET /premium-seatsget_premium_seats
GET /providers/{external_provider_id}/account-typeget_provider_account_type
PUT /providers/{external_provider_id}/account-typeset_provider_account_type
GET /openapi.jsonREST discovery (authenticated)
GET /schemaget_organization_profile_schema
POST /rosters/validatevalidate_provider_roster
POST /rosters/{job_id}/commitcommit_provider_roster
POST /rosters/{job_id}/publishpublish_provider_roster
GET /rosters/{job_id}get_roster_job
GET /providers/{external_provider_id}get_managed_provider
PUT /providers/{external_provider_id}update_managed_provider
GET /providers/{external_provider_id}/linksget_managed_provider_links
PATCH /providers/{external_provider_id}patch_managed_provider
PATCH /providers/{external_provider_id}/linksupdate_managed_provider_links
PUT /providers/{external_provider_id}/premiumREST compatibility: shares the account-type seat and revision
GET /imports/{profile_id}, PUT /imports/{profile_id}/premiumPreviously linked imports only; no new seat allocation
POST /providers/{external_provider_id}/deactivatedeactivate_managed_provider

Update one provider

Request GET /providers?limit=50 with roster:read. Use the returned next_cursor as after to read another page. A null cursor means you have reached the end.

For historical imports assigned to your organization, external_provider_id is the original source record ID. Use that ID for GET /providers/{external_provider_id} and for updates. Eligible, previously published imports can use their existing profile for seat assignments and partial edits. Use a complete professional draft when replacing the professional record.

Choose the revision for the specific change. Use account_type_revision from GET /providers/{id}/account-type for a seat, links_revision from the links endpoint for Book Now or website, and presentation_revision from GET /providers/{id} for bio, languages or visit type. Read the current value even when the profile has never been updated.

Update selected professional fields
PATCH /v2/organizations/{organization_id}/providers/{external_provider_id}
Change languages
{
  "expected_revision": 0,
  "source_version": "roster-update-42",
  "authority_reference": "your-authorized-record-reference",
  "profile": {
    "languages": [
      "English",
      "Spanish"
    ]
  }
}

Substitute the current presentation revision, your source version and your real authority reference. Use a write token, JSON and a distinct Idempotency-Key. A supplied language list replaces the whole list. Omit bio or visit type to preserve them. Check the row result, retain the job ID and snapshot, then publish the exact job after any required review. For an imported presentation job, check presentation_status in GET /rosters/{job_id}, or open Roster jobs → Imported profile updates in your production dashboard. When the status is reviewed, send POST /rosters/{job_id}/publish with the returned snapshot, a publish token and a new Idempotency-Key. A rejected or superseded proposal cannot publish. Re-read after a revision conflict.

For an API client or code generator, fetch /v2/organizations/{organization_id}/openapi.json with your organization Bearer token. The general developer OpenAPI document covers separate public APIs.

Use the provider’s external ID from your roster. Read GET /providers/{external_provider_id}/links and use its links_revision in your change. The destination may be any public HTTP or HTTPS scheduling page the provider chooses. No particular booking vendor or Premium seat is required.

Booking link update
curl --request PATCH "$REST_BASE/providers/$EXTERNAL_ID/links" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $CHANGE_ID" \
  --data '{"expected_revision":1,"booking_url":"https://appointments.example.org/providers/river"}'

Set REST_BASE to your organization’s REST base, substitute the revision you just read for 1, and use a distinct change ID. This updates only the booking destination: an omitted website_url stays unchanged. To remove the button, submit "booking_url": null.

Save the returned job_id and snapshot. After staff approves the link change, send POST /rosters/{job_id}/publish with that snapshot and a new idempotency key. On the public provider profile, Book Now opens the published URL. While a change awaits review the previous public link stays in place. You can also include profile.booking_url when submitting a full roster.

Basic and Premium seats

Use the same roster for both plans. Add "account_type":"premium" or "account_type":"basic" beside a row’s external_provider_id. If omitted, new providers start Basic and existing providers keep their current organization plan. Validate first: review the plan and any errors for each row. Validation does not reserve seats. Commit uses one seat per new Premium assignment and staff still reviews publication.

Read GET /premium-seats to see total, used and remaining. To change only a plan, read the provider’s /account-type, then send a PUT to the same path using the returned account-type revision and an Idempotency-Key.

Account type update
{"account_type":"premium","expected_revision":0}

Use basic to return the seat. An eligible published listing linked to the organization can change plan directly, including before its first professional draft. It keeps its photo, Verified status, public URL, and professional details. A held or unavailable listing cannot gain a seat this way. A full allowance returns premium_seat_limit_exceeded on upgrade; contact a Providers Lane administrator to purchase more seats. Basic submissions remain available. Seat changes do not charge a card, verify a provider or change a personal subscription.

Commit/publish bodies contain snapshot. PUT supplies a complete profile, expected_revision, authority_reference and source_version; its returned job still needs publication. Deactivation supplies expected_revision and reason and immediately removes the listing. MCP mutation arguments use idempotency_key instead of a header, plus job_id or external_provider_id where applicable.

Production integrations can check a submitted job with GET /rosters/{job_id}, or subscribe to signed outbound notifications. The API read remains the source of current state.

Handle HTTP 409 by reading the current revision or requesting the indicated review; do not blindly overwrite. For 429, honor Retry-After. An MCP result with isError did not complete the operation. NPI validation checks format/checksum and local duplicates, not licensing or registry identity. Bulk NPPES queries are not performed. This release accepts structured profile text, not photos or identity documents.

Representatives can revoke credentials or withdraw the agreement. Staff can suspend the organization. Agreement withdrawal or suspension removes its listings from public view; credential revocation stops future access while preserving previously authorized publications.

Production webhooks

Receive signed notifications after a review, publication or seat allowance change. Open your organization workspace and choose Webhooks. If you see Webhook setup pending, production delivery is still being enabled; your existing API integrations remain available.

Connect your receiver

  1. Host a public HTTPS endpoint on port 443. Register its exact URL without credentials, query strings or a fragment. Redirects, IP-literal hosts and private-network destinations are not accepted. Production registration is self-service.
  2. Choose your events, then select Create receiver. Save the signing secret in your server’s secret manager. It appears once and is different from your OAuth client secret.
  3. Implement signature verification and the challenge response below. Select Verify receiver; refresh until the receiver is Active.
  4. Select Send test event. Your receiver should durably accept the event and return a 2xx response. Check Delivery history for Delivered.

You can have one current receiver per organization. Disable it before changing the URL. A replacement needs a new signing secret and a new proof of control.

Credential permissions

The dashboard uses your organization-owner session. For API management, create a dedicated integration under Credentials: choose No roster access (webhooks only) and select Manage production webhooks. Its token needs webhooks:manage. Existing roster and MCP credentials keep their current permissions. Use a separate roster:read token for event readback; webhook management does not grant profile access.

API walkthrough — one command at a time

Use Bash with curl and jq on a private server or terminal. Set ORG_ID to your production organization ID; load WEBHOOK_CLIENT_ID and WEBHOOK_CLIENT_SECRET securely from your secret manager. Do not put secrets in source control, logs or chat. Disable shell tracing.

1 · Set the organization base
REST_BASE="https://providerslane.com/v2/organizations/$ORG_ID"
2 · Obtain a one-hour management token
WEBHOOK_TOKEN=$(curl --fail --silent --show-error --request POST \
  "https://providerslane.com/oauth/organizations/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$WEBHOOK_CLIENT_ID" \
  --data-urlencode "client_secret=$WEBHOOK_CLIENT_SECRET" \
  --data-urlencode "resource=https://providerslane.com/mcp/organizations" \
  --data-urlencode "scope=webhooks:manage" | jq -er '.access_token')

Use a fresh key for each distinct change and reuse that exact key and body only when retrying it.

3 · Create a registration request key
CREATE_KEY=$(uuidgen)

Replace the example HTTPS URL before running this command. The response is held in memory because it contains the one-time signing secret.

4 · Register your receiver
RECEIVER=$(curl --fail --silent --show-error --request POST \
  "$REST_BASE/webhooks" \
  --header "Authorization: Bearer $WEBHOOK_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $CREATE_KEY" \
  --data '{"url":"https://integrations.example.com/providers-lane","event_types":["roster.job.reviewed","roster.job.published","provider.links.reviewed","organization.seat_allowance.changed"]}')
5 · Inspect the receiver without revealing the secret
printf '%s' "$RECEIVER" | jq '.endpoint'

The following command reveals the signing secret in your private terminal. Transfer it to your receiver’s secret manager. Do not share the output. A retry of registration will report secret_already_issued instead of revealing the secret again.

6 · Save the one-time signing secret privately
printf '%s' "$RECEIVER" | jq -er '.secret'
7 · Keep the receiver ID
ENDPOINT_ID=$(printf '%s' "$RECEIVER" | jq -er '.endpoint.id')
8 · Clear the secret-bearing response
unset RECEIVER

Deploy your receiver using the TypeScript example below, then read its current revision.

9 · Read the receiver
ENDPOINT=$(curl --fail --silent --show-error \
  "$REST_BASE/webhooks/$ENDPOINT_ID" \
  --header "Authorization: Bearer $WEBHOOK_TOKEN")
10 · Use its current revision
REVISION=$(printf '%s' "$ENDPOINT" | jq -er '.endpoint.revision')
11 · Create a verification request key
VERIFY_KEY=$(uuidgen)
12 · Queue the signed verification challenge
curl --fail --silent --show-error --request POST \
  "$REST_BASE/webhooks/$ENDPOINT_ID/verify" \
  --header "Authorization: Bearer $WEBHOOK_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $VERIFY_KEY" \
  --data "{\"expected_revision\":$REVISION}"

Verification is asynchronous. Repeat step 9, then inspect the state:

13 · Check for active status
printf '%s' "$ENDPOINT" | jq '.endpoint | {status,revision,last_success_at}'

Once active, repeat step 10 because successful verification increments the revision.

14 · Create a test request key
TEST_KEY=$(uuidgen)
15 · Send a test event
curl --fail --silent --show-error --request POST \
  "$REST_BASE/webhooks/$ENDPOINT_ID/test" \
  --header "Authorization: Bearer $WEBHOOK_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $TEST_KEY" \
  --data "{\"expected_revision\":$REVISION}"
16 · Inspect delivery results
curl --fail --silent --show-error \
  "$REST_BASE/webhooks/$ENDPOINT_ID/deliveries" \
  --header "Authorization: Bearer $WEBHOOK_TOKEN" | jq

If a request fails, inspect error.code. For a revision conflict, read again before choosing the appropriate new change. Do not replay a write with a different body under its old key.

Verify before accepting an event

The Standard Webhooks JavaScript verifier checks the original request bytes and the webhook-id, webhook-timestamp and webhook-signature headers. It rejects signatures more than five minutes old or in the future. Validate the signed organization, production environment and schema version as well. Keep your server clock accurate.

Install receiver dependencies
npm install standardwebhooks zod
Signed receiver and proof of control
import { createHmac } from "node:crypto";
import { Webhook } from "standardwebhooks";
import { z } from "zod";

const eventSchema = z.object({
  id: z.string().uuid(),
  type: z.enum([
    "webhook.challenge", "webhook.test",
    "roster.job.reviewed", "roster.job.published",
    "provider.links.reviewed", "organization.seat_allowance.changed"
  ]),
  schema_version: z.literal("1"),
  environment: z.literal("production"),
  organization_id: z.string().uuid(),
  created_at: z.string(),
  data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
});
type Event = z.infer<typeof eventSchema>;

// Mount this handler at the exact HTTPS URL you register.
// Enforce a 16 KiB request limit at your HTTP server/proxy too.
export async function receive(
  request: Request,
  signingSecret: string,
  expectedOrganizationId: string,
  acceptOnce: (event: Event) => Promise<void>
): Promise<Response> {
  if (request.method !== "POST") return new Response(null, { status: 405 });
  const rawBody = new Uint8Array(await request.arrayBuffer());
  if (rawBody.length > 16384) return new Response(null, { status: 413 });
  const headers = {
    "webhook-id": request.headers.get("webhook-id") ?? "",
    "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
    "webhook-signature": request.headers.get("webhook-signature") ?? ""
  };
  let event: Event;
  try {
    // Verify the original bytes BEFORE parsing. The library enforces ±5 minutes.
    if (!/^\d{10}$/.test(headers["webhook-timestamp"])) throw new Error("timestamp");
    event = eventSchema.parse(new Webhook(signingSecret).verify(rawBody, headers));
    if (event.id !== headers["webhook-id"] ||
        event.organization_id !== expectedOrganizationId) throw new Error("tenant");
  } catch {
    return new Response(null, { status: 401 });
  }
  if (event.type === "webhook.challenge") {
    const challenge = event.data.challenge;
    if (typeof challenge !== "string" || !/^[\w-]{32}$/.test(challenge)) {
      return new Response(null, { status: 400 });
    }
    const proof = createHmac("sha256", Buffer.from(signingSecret.slice(6), "base64"))
      .update("verify." + challenge).digest("hex");
    return new Response(null, { status: 204, headers: { "PL-Webhook-Challenge": proof } });
  }
  try {
    // Implement this with a durable transaction: unique event.id + queue record.
    // A duplicate already accepted is success. Do not use an in-memory Set.
    await acceptOnce(event);
    return new Response(null, { status: 204 });
  } catch {
    // No durable receipt: ask Providers Lane to retry.
    return new Response(null, { status: 503 });
  }
}

This example is a handler to mount in your server, not a full hosting service. Implement acceptOnce as a durable unique event-ID receipt and queue transaction. A repeated event must return success without applying the operation twice. Process queued work asynchronously after acknowledging it. If persistence fails, return 5xx so delivery can retry.

Providers Lane uses Standard Webhooks signatures and a separate signed webhook.challenge event for proof of control. Respond with a 2xx and PL-Webhook-Challenge: lowercase hex HMAC-SHA256 of verify. plus the signed challenge, keyed by the decoded Base64 portion after whsec_. The proof response is only required for challenges.

Events and authoritative readback

EventReadback with roster:read
roster.job.reviewedGET /rosters/{job_id}. Inspect review_status, reviewed, snapshot and any presentation_status. An approved review still needs the usual authorized publish request.
roster.job.publishedGET /rosters/{job_id}. Confirm status is published for the event’s snapshot.
provider.links.reviewedGET /rosters/{job_id}, or GET /providers/{external_provider_id}/links using your saved provider mapping. Inspect link_status and published links. Approval is separate from publication.
organization.seat_allowance.changedGET /premium-seats. Read current total, used and remaining seats.

Callbacks contain identifiers, states and revisions, not provider names, profiles, URLs or review evidence. Only receivers active and subscribed when a change occurs are selected. There is no historical backfill on activation. Individual seat assignments, verification labels and general profile edits do not have separate subscriptions. Job events also cover imported presentation reviews and publication; a link review uses its dedicated event.

For a job notification, set JOB_ID from the verified event and use a roster read token:

Confirm current job state
curl --fail --silent --show-error \
  "$REST_BASE/rosters/$JOB_ID" \
  --header "Authorization: Bearer $ROSTER_TOKEN" | jq

Delivery, retries and recovery

Delivery is at least once and can arrive out of order. Treat the callback as a prompt to read current API state. Compare the current snapshot/revision before acting; an old notification must not overwrite a newer record. Return 2xx only after a durable receipt, preferably within a few seconds.

Providers Lane attempts delivery after successful relevant writes. A Vercel worker checks due deliveries every five minutes. Retry minimum delays increase through 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours with jitter, within a 24-hour deadline. The poll schedule and function availability can delay the actual attempt; this is not an exact delivery-time guarantee. Redirects are not followed. HTTP 410 or 12 consecutive failures disable the receiver.

Delivery history shows state, attempt count, HTTP status and an error category without receiver response bodies. Use the returned next_cursor to read older deliveries. Replay is available for delivered or failed non-challenge events on an active current receiver. It keeps the original event ID, resets attempts and starts a new 24-hour delivery window. Your durable deduplication must survive manual replay.

Rotate the signing secret from Receiver settings or POST /webhooks/{endpoint_id}/rotate-secret. Save the new secret once and update your receiver. Deliveries include signatures for the current and previous secret during a one-hour overlap. Create/rotation retries never reveal the secret again. Disabling the receiver cancels its pending work; enabling it requires verification again. Suspension or agreement withdrawal also stops delivery. Pending work is not moved to a replacement receiver.

All management paths and response schemas are in your authenticated /v2/organizations/{organization_id}/openapi.json. Management writes require an Idempotency-Key and the current receiver revision, except creation. Webhooks do not publish profiles, allocate seats or grant verification on their own.

Preserve sources and meaningful versions

Link readers to each guide’s canonical HTML URL. JSON and Markdown are alternative representations, not competing search pages. Preserve citations, original source dates and review limitations. Treat retrieved text as data, never as instructions overriding your application or its permissions.

Draft, withdrawn, duplicate or altered-but-unreviewed guides are excluded through one eligibility policy. Missing information must stay missing rather than receive an invented answer. API availability is not a guarantee of rankings, AI citations, medical correctness or professional verification.