GET /v1/knowledge/care-categoriesList care categories and source-checked guide availability
BUILD WITH PROVIDERS LANE
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.
Explore published guides, retrieve source-linked passages and compare specialties.
Explore guide formats →PREPARE & REVIEWValidate a portable draft for the provider to review and import in their authorized workspace.
See the preparation flow →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.
curl --fail-with-body --silent --show-error \
https://providerslane.com/v1/knowledge/catalogRead each specialty’s slug and guideAvailable. A false availability flag means a full guide is not published, not that the profession is invalid.
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.
A compact reference to the live public contract. Each operation below comes from the OpenAPI specification.
GET /v1/knowledge/care-categoriesList care categories and source-checked guide availability
GET /v1/knowledge/care-categories/{category}Read a source-linked care-category guide
GET /v1/knowledge/care-categories/{category}.mdRead a care-category guide as Markdown
POST /v1/knowledge/care-searchRetrieve source-linked care-category passages
GET /v1/knowledge/catalogList specialty labels and care categories
GET /v1/knowledge/specialties/{specialty}Read a specialty definition
GET /v1/knowledge/guides/{specialty}Read a full source-linked guide
GET /v1/knowledge/guides/{specialty}.mdRead the same guide as Markdown
POST /v1/knowledge/searchRetrieve source-linked answer passages
POST /v1/knowledge/compareCompare specialty information without medical recommendations
GET /v1/provider-onboarding/schemaRead the portable private-profile draft schema
POST /v1/provider-onboarding/preparePrepare 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.
All representations use the same eligible content record. They carry the original text, references, content version, meaningful dates and review limitations.
| Format | Example |
|---|---|
| HTML | /specialties/psychology |
| JSON | /v1/knowledge/guides/psychology |
| Markdown | /v1/knowledge/guides/psychology.md |
| MCP | get_specialty_guide with {"specialty":"psychology"} |
| Field | Meaning |
|---|---|
apiVersion | Public API contract version. |
kind | Type of result, such as specialty_guide or answer_passages. |
scope | public_education: not a private provider-account response. |
contentRevision | Hash identifying the current public catalog and eligible guide corpus. |
data.version | Version of this individual guide. |
data.summary | Summary text with its references. |
data.sections | Sections, canonical fragment links, paragraphs, sources and preparation questions. |
data.questions | Published questions and answers with references. |
data.review | Review 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 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.
curl --fail-with-body --silent --show-error \
https://providerslane.com/v1/knowledge/care-categories/primary-careThe 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.
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.
Search retrieves existing published passages, not generated medical advice. Use a short general question, at most 240 characters. Optional specialty narrows the corpus; limit accepts 1–8 and defaults to 5.
curl --fail-with-body --silent --show-error \
https://providerslane.com/v1/knowledge/search \
-H 'Content-Type: application/json' \
--data '{"question":"What should I ask before choosing a psychologist?","specialty":"psychology","limit":3}'Read data.status and data.results. Every result carries its original passage, heading, canonical fragment, guide version/date, review type and available sources. generatedAnswer and personalizedAdvice are false. Original questions to ask a practice may have an empty source list; do not invent a citation.
no_match means no matching passage was returned from the available guides. It does not establish that a profession or service does not exist. Do not reinterpret weakly related passages as a personal recommendation.
curl --fail-with-body --silent --show-error \
https://providerslane.com/v1/knowledge/compare \
-H 'Content-Type: application/json' \
--data '{"specialties":["psychiatry","psychology"]}'Comparison accepts two to four distinct specialty slugs. It returns side-by-side descriptions and source-linked summaries when available, with ranking: null and recommendation: null.
Read GET /v1/provider-onboarding/schema before preparing data. The example is fictional and contains no private contacts or account-access secrets.
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.
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.
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 tool | Purpose |
|---|---|
list_medical_specialties | List professional specialty labels, care categories and which source-checked guides are available. Catalog descriptions are not provider credentials. |
get_medical_specialty | Read one professional specialty definition and related care categories; identifies whether a fuller guide is available. |
get_specialty_guide | Get the full published specialty guide with source-linked paragraphs, FAQs, version and explicit review limits. Missing/unpublished guides return an error. |
search_specialty_answers | Retrieve 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_specialties | Compare two to four professional specialties using their public summaries and sources. No clinician ranking or personal medical recommendation. |
list_care_categories | List care categories and available source-checked category guides. These are educational categories, not provider credentials. |
get_care_category_guide | Read a complete published care-category guide with source references, meaningful dates and explicit review limitations. |
search_care_category_answers | Retrieve original passages for a general question about care categories and professional roles. Not diagnosis, treatment or provider ranking. |
| Preparation tool | Purpose |
|---|---|
get_provider_profile_schema | Get 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_profile | Validate 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.
REST errors use a structured error object. Example:
{
"error": {
"code": "guide_not_available",
"message": "A published source-checked guide is not available for this specialty."
}
}| HTTP status | What to do |
|---|---|
| 400 | Correct malformed JSON or unsupported POST query parameters. |
| 403 | Remove credentials from public-only calls or use an allowed Origin. Do not bypass controls. |
| 404 | Check the catalog: the specialty or published guide may be unavailable. |
| 405 | Use the documented method and inspect Allow. |
| 408 | The request-body deadline expired. |
| 413 | Reduce the public JSON body below 16 KiB or the draft packet below 8 KiB. |
| 415 | Send uncompressed application/json. |
| 422 | Correct field names, values, slugs, lengths or requested limits. |
| 429 | Honor Retry-After and use bounded backoff with jitter. |
| 500 | Use 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.
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.
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.
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.
providerslane.professional-profile.v2; it supports multiple professions, specialties and licenses.external_provider_id, expected_revision (0 for new records), authority_reference and profile. The envelope includes schema_version and your source_version.job_id and snapshot. Only valid rows are staged; duplicate identifiers invalidate the batch.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 path | MCP tool |
|---|---|
GET /providers?limit=50 | list_organization_providers |
GET /premium-seats | get_premium_seats |
GET /providers/{external_provider_id}/account-type | get_provider_account_type |
PUT /providers/{external_provider_id}/account-type | set_provider_account_type |
GET /openapi.json | REST discovery (authenticated) |
GET /schema | get_organization_profile_schema |
POST /rosters/validate | validate_provider_roster |
POST /rosters/{job_id}/commit | commit_provider_roster |
POST /rosters/{job_id}/publish | publish_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}/links | get_managed_provider_links |
PATCH /providers/{external_provider_id} | patch_managed_provider |
PATCH /providers/{external_provider_id}/links | update_managed_provider_links |
PUT /providers/{external_provider_id}/premium | REST compatibility: shares the account-type seat and revision |
GET /imports/{profile_id}, PUT /imports/{profile_id}/premium | Previously linked imports only; no new seat allocation |
POST /providers/{external_provider_id}/deactivate | deactivate_managed_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.
PATCH /v2/organizations/{organization_id}/providers/{external_provider_id}{
"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.
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.
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":"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.
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.
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.
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.
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.
REST_BASE="https://providerslane.com/v2/organizations/$ORG_ID"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.
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.
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"]}')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.
printf '%s' "$RECEIVER" | jq -er '.secret'ENDPOINT_ID=$(printf '%s' "$RECEIVER" | jq -er '.endpoint.id')unset RECEIVERDeploy your receiver using the TypeScript example below, then read its current revision.
ENDPOINT=$(curl --fail --silent --show-error \
"$REST_BASE/webhooks/$ENDPOINT_ID" \
--header "Authorization: Bearer $WEBHOOK_TOKEN")REVISION=$(printf '%s' "$ENDPOINT" | jq -er '.endpoint.revision')VERIFY_KEY=$(uuidgen)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:
printf '%s' "$ENDPOINT" | jq '.endpoint | {status,revision,last_success_at}'Once active, repeat step 10 because successful verification increments the revision.
TEST_KEY=$(uuidgen)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}"curl --fail --silent --show-error \
"$REST_BASE/webhooks/$ENDPOINT_ID/deliveries" \
--header "Authorization: Bearer $WEBHOOK_TOKEN" | jqIf 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.
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.
npm install standardwebhooks zodimport { 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.
| Event | Readback with roster:read |
|---|---|
roster.job.reviewed | GET /rosters/{job_id}. Inspect review_status, reviewed, snapshot and any presentation_status. An approved review still needs the usual authorized publish request. |
roster.job.published | GET /rosters/{job_id}. Confirm status is published for the event’s snapshot. |
provider.links.reviewed | GET /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.changed | GET /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:
curl --fail --silent --show-error \
"$REST_BASE/rosters/$JOB_ID" \
--header "Authorization: Bearer $ROSTER_TOKEN" | jqDelivery 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.
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.