> ## Documentation Index > Fetch the complete documentation index at: https://docs.linkxg.com/llms.txt > Use this file to discover all available pages before exploring further. # Adoption state > Read a tenant's adoption journey — maturity, milestones, next-best-action, coverage, risk signals, and success plan The adoption API exposes a tenant's progress through the LinkXG network as structured, machine-readable state. It is the contract behind the in-product guidance experience — the maturity ladder, the "do this next" prompt, the coverage cells, the drift-watch feed, and the renewable success plan. Every endpoint is tenant-scoped: the data returned always belongs to the authenticated user's company. These reads are designed for first-party surfaces (the application Home and the Manual), but they are part of the documented API and behave like any other authenticated endpoint. ## Concepts A tenant's adoption is modelled as one state aggregate with four relations. | Concept | Meaning | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Maturity rung** | Where the tenant sits on the five-rung ladder: `ONBOARDED → CONNECTED → EXCHANGING → TRACED → STRATEGIC`. | | **Health band** | A coarse health signal: `ONBOARDING`, `HEALTHY`, `AT_RISK`, or `DRIFTING`. `healthScore` is an integer that is `null` until first computed. | | **Milestone** | A unit of progress with a `status` (`LOCKED`, `AVAILABLE`, `IN_PROGRESS`, `DONE`, `NOT_APPLICABLE`), a `chapter` (1–7), and a `dependsOn` list of other milestone keys. A locked milestone carries `lockedReasons` naming the unmet dependency. | | **Path profile** | `SUPPLIER` or `LINKXG`, derived from the subscription tier — it determines which milestones a tenant instantiates. | | **Success plan** | The tenant's single `ACTIVE` plan: a title, a rough target date, and a list of objectives that each map to milestone keys. | | **Risk signal** | A drift-watch item (an unaccepted invitation, an unviewed policy, a failing integration, stale data, a stalled cascade, an unanswered request) with a severity and resolution state. | Milestones gated behind a paid capability carry `paidTeaser: true`, a `requiredCapability`, and an `upgradeContext` describing the recommended upgrade — see [Upgrade context](/developers/rate-limits#upgrade-context). *** ## Get the adoption state Returns the full state: maturity rung, health band and score, network density, path profile, and the complete ordered list of milestones with their status and lock reasons. ```bash theme={null} curl https://api.linkxg.com/api/v1/tenant/adoption/state \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` **Response:** ```json theme={null} { "success": true, "data": { "companyId": "uuid", "currentMaturityRung": "CONNECTED", "pathProfile": "SUPPLIER", "healthScore": 72, "healthBand": "HEALTHY", "networkDensity": 4, "lastRecomputedAt": "2026-06-24T09:00:00.000Z", "version": 7, "milestones": [ { "key": "first_product_published", "chapter": 2, "internalStage": "S3", "status": "DONE", "completionMode": "EVENT_DETECTED", "triggerEvent": "product.created", "dependsOn": [], "displayOrder": 10, "requiredCapability": null, "paidTeaser": false, "lockedReasons": [], "completedAt": "2026-06-20T11:30:00.000Z", "upgradeContext": null }, { "key": "first_data_exchanged", "chapter": 4, "internalStage": "S7", "status": "LOCKED", "completionMode": "EVENT_DETECTED", "triggerEvent": "product.viewed", "dependsOn": ["first_connection_active"], "displayOrder": 40, "requiredCapability": null, "paidTeaser": false, "lockedReasons": [{ "unmetDependencyKey": "first_connection_active" }], "completedAt": null, "upgradeContext": null } ] } } ``` *** ## Get the next best action Returns the single most valuable unblocked milestone (`nextBestAction`), plus the full `available` and `locked` lists and an optional `nextUpgradePrompt`. Each milestone carries `unlocks` (how many downstream steps it frees) and a plain-language `becauseOf` reason. This is what the application renders as "do this next". ```bash theme={null} curl https://api.linkxg.com/api/v1/tenant/adoption/next-best-action \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` **Response (abridged):** ```json theme={null} { "success": true, "data": { "companyId": "uuid", "currentMaturityRung": "CONNECTED", "nextBestAction": { "key": "first_connection_active", "chapter": 3, "status": "AVAILABLE", "unlocks": 3, "becauseOf": "Connect a partner to start exchanging data.", "lockedReasons": [] }, "available": [ { "key": "first_connection_active", "status": "AVAILABLE" } ], "locked": [ { "key": "first_data_exchanged", "status": "LOCKED", "lockedReasons": [{ "unmetDependencyKey": "first_connection_active" }] } ], "nextUpgradePrompt": null } } ``` *** ## Complete a milestone A small number of milestones have no automatic event trigger and are completed manually. Pass the milestone `key` in the path. The body is optional: `evidenceRef` links the producing record, and `expectedVersion` enables optimistic-concurrency control (a stale version returns `409`). ```bash theme={null} curl -X POST https://api.linkxg.com/api/v1/tenant/adoption/milestones/company_profile_reviewed/complete \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "expectedVersion": 7 }' ``` The response is the recomputed adoption state, identical in shape to `GET /tenant/adoption/state`. Completing a milestone whose dependencies are unmet returns `403`; an unknown key returns `404`. *** ## Get coverage cells Returns the macro coverage cells shown on the application Home — products on the network, partners connected, data flowing, and so on. Each cell reports whether the tenant is `capable` of the activity (entitlement), whether it has `achieved` it, a `count`, and a `viewedCount`. ```bash theme={null} curl https://api.linkxg.com/api/v1/tenant/adoption/coverage \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` **Response:** ```json theme={null} { "success": true, "data": { "cells": [ { "key": "products", "label": "Products on the network", "capable": true, "achieved": true, "count": 42, "viewedCount": 18 }, { "key": "partners", "label": "Partners connected", "capable": true, "achieved": true, "count": 6, "viewedCount": 0 } ] } } ``` *** ## Get risk signals Returns the active drift-watch signals for the tenant, most recent first. Use the optional `limit` query parameter to cap the result count. ```bash theme={null} curl "https://api.linkxg.com/api/v1/tenant/adoption/risk-signals?limit=20" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` **Response:** ```json theme={null} { "success": true, "data": { "signals": [ { "id": "uuid", "kind": "INVITATION_UNACCEPTED", "severity": "MEDIUM", "resolution": "AUTO_NUDGED", "escalatedToHuman": false, "subjectRef": { "connectionId": "uuid" }, "detectedAt": "2026-06-22T08:15:00.000Z", "resolvedAt": null } ] } } ``` `kind` is one of `INVITATION_UNACCEPTED`, `POLICY_UNVIEWED`, `INTEGRATION_FAILING`, `DATA_STALE`, `CASCADE_STALLED`, `REQUEST_UNANSWERED`. `resolution` walks the ladder `OPEN → AUTO_NUDGED → REO_PROMPTED → ESCALATED → RESOLVED`. *** ## The success plan A tenant has at most one `ACTIVE` success plan. Read it, create it, or renew it. ### Read ```bash theme={null} curl https://api.linkxg.com/api/v1/tenant/adoption/success-plan \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` Returns the active plan, or `data: null` when none exists: ```json theme={null} { "success": true, "data": { "id": "uuid", "title": "Get three buyers exchanging data this quarter", "targetDate": "2026-09-30T00:00:00.000Z", "status": "ACTIVE", "renewedFromId": null, "objectives": [ { "label": "Connect three buyers", "milestoneKeys": ["first_connection_active"], "met": false } ], "createdAt": "2026-06-18T10:00:00.000Z", "updatedAt": "2026-06-18T10:00:00.000Z" } } ``` ### Create Requires the `OWNER` or `ADMIN` role. Returns `409` if an active plan already exists. ```bash theme={null} curl -X POST https://api.linkxg.com/api/v1/tenant/adoption/success-plan \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Get three buyers exchanging data this quarter", "targetDate": "2026-09-30T00:00:00.000Z", "objectives": [ { "label": "Connect three buyers", "milestoneKeys": ["first_connection_active"], "met": false } ] }' ``` ### Renew Renewing marks the predecessor `RENEWED` and creates a new `ACTIVE` plan that carries the prior objectives forward. Pass the predecessor's id as `fromPlanId`. The response is the recomputed adoption state. ```bash theme={null} curl -X POST https://api.linkxg.com/api/v1/tenant/adoption/success-plan/renew \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fromPlanId": "uuid", "targetDate": "2026-12-31T00:00:00.000Z" }' ``` *** ## Next steps Resolve the upgrade card behind a gated milestone Browse the complete API documentation