Use Cases

Use the ScopeWorth Customer API to bring delivery evidence into client reporting, in-house planning and investment reviews, or reviews with external development partners. These recipes describe integrations you can build on your own server, using the published API operations. They are illustrative workflows, not built-in scheduled jobs or vendor integrations.

Start with a scoped, expiring key and the verified organization/workspace route. Discover client and project IDs from your own responses. Every request still checks the key's scopes, its creator's current permissions, target ownership, effective plan and quotas. See Authentication and API keys and Plans and limits.

Prepare recurring client reports

For agencies and consultancies: prepare a consistent delivery review before the weekly client meeting or the monthly account review. Bring together what shipped, what changed and what it cost without rebuilding the same report by hand.

1. Use directory.read to choose the client's project and an explicit reporting period.
2. Read reports.facts. Keep warnings, missing coverage and inferred evidence alongside the numbers.
3. Build a schema-compatible composition and call reports.preview. Review the period, currency, layout and evidence with the account team. Optional reports.narrative prose needs its own eligibility and review.
4. Call reports.create after approval and retain the returned identifiers. Read the saved snapshot with reports.read and download its PDF with reports.pdf.

Example: your own monthly reporting job prepares a preview for a fictional client, Harbor Studio. An account lead reviews it, then your integration saves an immutable snapshot for the review. Your system owns scheduling and distribution; creating a report does not email it to the client.

Start with the generated facts request below. Its project IDs and dates are synthetic: replace them with your directory response and chosen period.

curl --request GET "$SCOPEWORTH_API_BASE/organizations/example-org/workspaces/example-workspace/report-builder/facts?projectId=11111111-1111-4111-8111-111111111111&start=2026-01-01&end=2026-03-31" \
  --header "Authorization: Bearer $SCOPEWORTH_API_KEY"

Follow the full report workflow for request bodies, snapshots, PDFs and recovery.

Review scope changes before a client call

For agencies and consultancies: turn a change-request discussion into an evidence review before deciding on a revised statement of work.

1. Select the project with directory.read and read scope.read for its documented period and scope comparison.
2. Use forensics.read to inspect the underlying delivery evidence. Separate declared links, inferred relationships and untraced work.
3. Where an issue needs a recorded review, use investigations.create, add a contextual note with investigations.noteCreate, and follow the supported investigation/package workflow.

Example: the client asks why a release moved. Your internal account portal presents the original scope and the available post-baseline evidence beside the team's explanation. A delivery lead reviews the evidence before proposing a change order. Counts or inferred relationships alone do not prove who requested a change or whether it is billable.

curl --request GET "$SCOPEWORTH_API_BASE/organizations/example-org/workspaces/example-workspace/projects/11111111-1111-4111-8111-111111111111/scope-creep?start=2026-10-01&end=2026-10-07&tz=UTC" \
  --header "Authorization: Bearer $SCOPEWORTH_API_KEY"

See the operation's API reference and the investigation workflow.

Support invoice reviews with evidence

For agencies and consultancies: prepare evidence for a finance or account-manager review when a client questions an invoice.

For companies outsourcing development: compare your development partner's invoice with the recorded delivery, scope and costs. Use the existing invoiceDefense.read operation for the evidence review; its API name stays the same across audiences. Retain missing inputs and assumptions, and bring unresolved questions to your partner.

1. Submit authorized commercial inputs, such as recorded time or an invoice, using commercial.timeEntry and commercial.invoice, or validate and commit an appropriate import.
2. Read invoiceDefense.read and inspect its coverage and limitations before using its conclusions.
3. Use the report workflow to prepare a reviewed client-facing snapshot. Preserve currency, date boundaries and the distinction between actual and estimated costs.

Example: your finance system sends a fictional project's invoice and recorded time to ScopeWorth. Your account team reads the evidence before explaining the invoice to the client. Your integration controls the finance-system connection; the Customer API does not promise an accounting-system sync or calculate tax and payment settlement for you.

Supplier-review example: your organization imports an agreed engagement budget and the partner's invoice, then prepares a supplier delivery report for a joint review. CSV or manual inputs can start the review without the supplier's repository credentials. This does not approve payment, certify contractual acceptance or grant access to supplier systems.

curl --request GET "$SCOPEWORTH_API_BASE/organizations/example-org/workspaces/example-workspace/invoice-defense?projectId=11111111-1111-4111-8111-111111111111&start=2026-10-01&end=2026-10-07&tz=UTC&mode=facts" \
  --header "Authorization: Bearer $SCOPEWORTH_API_KEY"

See Commercial inputs for units, required fields and current permissions.

Connect project setup and commercial inputs

For agencies and consultancies: connect your own engagement onboarding process to the ScopeWorth client register and its supported commercial inputs.

1. Check clients.list and directory.read for existing records before creating anything.
2. Use clients.create or clients.update with the documented client/project contract; retain returned IDs and versions.
3. Add the supported engagement rates and budget with commercial.rates and commercial.budget, or use the upload → validate → commit import sequence for a supported data kind.

Example: after your team approves an engagement in its CRM, your server prepares the client/project record and the approved commercial inputs in ScopeWorth. Use IDs from the preceding responses and review mappings before a write. A matching name alone is not a reliable identity, and an API key does not grant access to every workspace.

Start by discovering the current directory:

curl --request GET "$SCOPEWORTH_API_BASE/organizations/example-org/workspaces/example-workspace/directory" \
  --header "Authorization: Bearer $SCOPEWORTH_API_KEY"

Follow Clients and projects, Commercial inputs and Imports. Keep one idempotency key for an unchanged mutation attempt; reconcile uncertain outcomes before trying a new write.

Bring delivery evidence to internal investment reviews

For in-house development teams: bring project-level delivery evidence into the review tools your engineering, product and finance teams already use.

1. Choose a project and period, then read commandCenter.read and confidence.read to understand the available evidence and its coverage.
2. Use aiEconomics.read when eligible to review the documented AI economics evidence, retaining estimates, missing inputs and uncertainty.
3. If your team needs to explore capacity assumptions, use scenarios.seed and the documented scenario creation/update workflow. Keep scenarios separate from observed results.

Example: a platform team prepares an investment review for a fictional migration initiative. Its internal dashboard shows delivery evidence and cost context, with confidence limitations visible. A scenario compares a proposed capacity change; it is a planning estimate, not a promise of future savings.

curl --request GET "$SCOPEWORTH_API_BASE/organizations/example-org/workspaces/example-workspace/command-center" \
  --header "Authorization: Bearer $SCOPEWORTH_API_KEY"

See Capacity scenarios, Assumptions and the API reference. Keep reporting at project, client and team level; avoid individual developer rankings or productivity scores.

Check data readiness before a delivery handoff

For agencies, in-house teams and companies working with external development partners: check whether an upcoming review has enough connected or imported evidence, and make gaps visible before the handoff.

1. Read dataSources.read, connections.list and confidence.read to inspect current source state and coverage.
2. For a supported CSV kind, call imports.upload, inspect imports.validate, and review the mappings and skipped-row reasons before imports.commit.
3. Retain the batch ID and use imports.history and imports.skipped to reconcile the outcome. Re-read the relevant evidence after the import completes.

Example: your own server checks readiness before Friday's client report and shows the delivery team that a time-data import needs attention. An authorized person reviews the validation before commit. A connected source or successful upload alone is not proof that complete, current project evidence exists.

curl --request GET "$SCOPEWORTH_API_BASE/organizations/example-org/workspaces/example-workspace/confidence?projectId=11111111-1111-4111-8111-111111111111&start=2026-10-01&end=2026-10-07&tz=UTC" \
  --header "Authorization: Bearer $SCOPEWORTH_API_KEY"

Follow Imports for the accepted data kinds, limits and recovery paths. Your integration owns its polling and notifications; honor Retry-After and use a bounded backoff.

Build and operate your integration

• Run requests on your server. Put SCOPEWORTH_API_BASE and SCOPEWORTH_API_KEY in server environment variables; never paste a real key into this documentation or ship it in browser code.
• Start with the least privileges needed. Check the operation's scope, creator action, eligible plans and schema in the API reference.
• Use actual response IDs and versions. The examples above are independent synthetic requests, not a sequence of real customer records.
• Review writes and evidence before external distribution. Scheduling, messaging, recipients and provider consent belong to your integration or the supported application workflows.
• Retain warnings, evidence-window limits and unknown values. A missing figure is not a measured zero; a scenario is not an achieved result.
• Follow error recovery for authorization, plan, validation, rate-limit and uncertain-write outcomes.