Adoption state

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.

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.

curl https://api.linkxg.com/api/v1/tenant/adoption/state \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "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”.

curl https://api.linkxg.com/api/v1/tenant/adoption/next-best-action \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (abridged):

{
  "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).

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.

curl https://api.linkxg.com/api/v1/tenant/adoption/coverage \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "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.

curl "https://api.linkxg.com/api/v1/tenant/adoption/risk-signals?limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "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

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:

{
  "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.

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.

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" }'

Overview

Suppliers

Buyers

Developers

Account & Billing

API Reference

Adoption state

Concepts

Get the adoption state

Get the next best action

Complete a milestone

Get coverage cells

Get risk signals

The success plan

Read

Create

Renew

Next steps

Upgrade context

API Reference

​Concepts

​Get the adoption state

​Get the next best action

​Complete a milestone

​Get coverage cells

​Get risk signals

​The success plan

​Read

​Create

​Renew

​Next steps

Upgrade context

API Reference

Concepts

Get the adoption state

Get the next best action

Complete a milestone

Get coverage cells

Get risk signals

The success plan

Read

Create

Renew

Next steps