Start with the mental model
A workspace API key is a server-to-server credential for your organisation. It gives your integration member-level access to clients who have explicitly consented to your firm, and only to the read endpoints listed in this guide.
Do I need an API key?
Probably not for day-to-day use. Your team can invite clients, view documents, manage workflow, generate packs, and send reminders from the normal web workspace without ever creating an API key.
API keys are for firms that want NHS Financial Planner to connect to another system, such as a CRM, practice management platform, reporting dashboard, data warehouse, or internal workflow tool. If a software provider, outsourced IT partner, or internal technical person has not asked for one, you can safely leave this page alone.
Common Use Cases
The API is designed for professional firms that already use NHS Financial Planner as a consented client workspace, but want selected data to appear inside their own operating systems.
Sync consented clients into your CRM
Pull the list of NHS clients who have granted your firm access, then match them to records in Xero Practice Manager, CCH, Intelligent Office, Salesforce, HubSpot, or your internal workflow tool.
Build a missing-evidence work queue
Read readiness signals and document counts so operations teams know who needs a TRS, payslip, P60, or other evidence before an adviser starts chargeable work.
Attach document summaries to case files
Fetch consented document metadata, extracted text, and analysis summaries for your internal client file, subject to your firm's data retention and GDPR policies.
Power internal dashboards
Create reporting for NHS client pipeline, evidence completeness, analysis progress, and adviser workload without asking staff to export spreadsheets manually.
Before You Begin
Admin access
Only organisation admins and owners can create or revoke API keys.
Client consent
The API only returns clients who have active consent for your organisation.
Secure storage
Have a secrets manager or protected integration setting ready before creating a key.
Send This to Your Software Provider
If you are not technical, the simplest next step is to send this section to the person or company that looks after your CRM, practice management software, reporting dashboards, or IT integrations.
Suggested message
Hi, We use NHS Financial Planner for our NHS client workflow. We would like to connect consented client data into our practice system. The API documentation is here: https://app.nhsfinancialplanner.co.uk/resources/workspace-api What we need: - Read the list of clients who have granted consent to our firm - Pull readiness/workflow status and document metadata - Optionally pull consented document details and analysis summaries Important limits: - API keys are read-only/member-level - They cannot invite clients, change settings, send reminders, use AI chat, or export audit logs - Access disappears immediately if a client revokes consent Please review the guide and tell us whether this can be connected to our system.
Create a key only when your provider is ready to store it securely. Do not email the secret API key. Share the documentation first, then provide the key through your provider's secure secrets process.
How Authentication Works
Create an API key from your organisation's API Keys page. The full key is shown once, so copy it into your secrets manager, integration platform, or CI variable immediately.
Send the key in the standard HTTP Authorization header. API keys start with nhsfp_live_.
New integrations should use the versioned /api/v1 routes. The older unversioned routes remain available for backwards compatibility.
Authorization: Bearer nhsfp_live_YOUR_KEYNHS Financial Planner stores only a SHA-256 hash of the full key. We cannot show it again after creation. Rotate by creating a new key, updating your integration, then revoking the old key.
Quickstart
Replace ORG_ID with your organisation identifier — visible in your workspace URL at https://app.nhsfinancialplanner.co.uk/org/YOUR_ORG_ID.
curl "https://app.nhsfinancialplanner.co.uk/api/v1/orgs/ORG_ID/clients?limit=25&offset=0" \
-H "Authorization: Bearer nhsfp_live_YOUR_KEY"A typical response includes consented clients, readiness signals, and pagination:
{
"clients": [
{
"client_user_id": "4f3c...",
"email": "client@example.com",
"name": "Dr Example",
"granted_at": "2026-04-30T10:15:00+00:00",
"document_count": 3,
"readiness": {
"label": "Ready for review",
"missing_evidence": [],
"analysed_document_count": 3
},
"workflow": {
"status": "ready_for_review",
"assigned_user_id": null,
"next_review_at": null
}
}
],
"total": 42,
"offset": 0,
"limit": 25
}Endpoint Reference
/api/v1/orgs/{org_id}/clientsList consented clients for the organisation, including readiness and workflow summary fields.
/api/v1/orgs/{org_id}/clients/{client_user_id}/workflowRead the current workflow state for a consented client.
/api/v1/orgs/{org_id}/clients/{client_user_id}/documentsList a consented client's available documents and analysis summaries.
/api/v1/orgs/{org_id}/clients/{client_user_id}/documents/{doc_id}Fetch one consented document, including extracted text and analysis when available.
List endpoints support pagination with offset and limit. Responses include total, offset, and limit so integrations can page safely. Current limits are capped to protect client data and service availability.
We treat these versioned endpoints as stable integration contracts. If your firm needs a new field or write action, contact us so it can be added deliberately with consent, audit, and backwards compatibility in mind.
Providers can also inspect the machine-readable OpenAPI schema at /api/openapi.json.
Permissions and Consent
What API keys can do
Read consented client lists, workflow summaries, document lists, and document details for the organisation that owns the key.
What API keys cannot do
- Invite clients or team members
- Change organisation settings, billing, or branding
- Send client reminders
- Use or read adviser AI chat
- Generate or download client packs
- View or export organisation audit logs
Client consent is always checked at request time. If a client revokes access, your API key immediately loses access to that client's documents without needing any change to your integration.
Keys carry explicit read scopes: clients:read, workflow:read, and documents:read. Admin, billing, branding, reminder, chat, and audit-export scopes are not available to API keys.
Errors and Rate Limits
Missing, invalid, expired, or revoked API key.
The key belongs to another organisation, the organisation is inactive, or the action requires a signed-in team member.
The requested client or document is not available through this consented workspace path.
Rate limit exceeded. Limits are applied by requesting IP address and by API key/organisation/endpoint, resetting every minute — wait and retry.
Per-endpoint rate limits
GET /api/v1/orgs/{org_id}/clients120 / minGET /api/v1/orgs/{org_id}/clients/{id}/workflow60 / minGET /api/v1/orgs/{org_id}/clients/{id}/documents120 / minGET /api/v1/orgs/{org_id}/clients/{id}/documents/{doc_id}120 / minBuild integrations to retry safely, avoid tight polling loops, and cache stable metadata where your own data protection policy allows.
Security Best Practice
Rotate keys deliberately
Create a new key, deploy it to your integration, confirm traffic is using it, then revoke the old key.
Store keys like passwords
Use a secrets manager or protected environment variable. Do not paste keys into tickets, spreadsheets, Slack, or client files.
Use separate keys per integration
Give each integration a descriptive name and expiry date so you can revoke one system without breaking everything else.
Need a new endpoint?
If your practice needs a write action or a data shape not listed here, contact us before building around a workaround. We keep the public API narrow so client consent, auditability, and adviser accountability remain clear.
Contact us about an integrationRelated workspace guides
These pages explain the professional workspace context around API access.