NeedsIQBack to NeedsIQ

Developers

NeedsIQ REST API (v1)

A read API over your NeedsIQ cases and their reports. Available on the Pro and Corporate plans. All responses are JSON unless noted.

Authentication

Create an API key in Settings. The key is shown once; store it securely. Send it on every request as a Bearer token:

curl https://needsiq.com/api/v1/ping \
  -H "Authorization: Bearer niq_live_..."

Requests are rate limited per key. A missing or invalid key returns 401; too many requests return 429 with a Retry-After header. If your plan no longer includes API access, existing keys stop working until you upgrade.

Endpoints

GET/api/v1/ping

Confirms your key works and returns your account context.

GET/api/v1/cases

Lists your cases, newest first. Query parameters: productLine (PROTECTION or MORTGAGE), status, limit (max 100), offset. Returns a list with total for pagination.

GET/api/v1/cases/:id

The full case: fact-find, advice, decisions, and the parsed report (protection D&N or mortgage suitability). Scoped to your account; an unknown id returns 404.

GET/api/v1/cases/:id/report.pdf

The rendered report as a PDF (Content-Type: application/pdf). Returns 409 if no report has been drafted yet.

GET/api/v1/clients

Not available in this version: clients are represented by their case. Use /api/v1/cases, which includes clientName and clientEmail.

Example

# List protection cases at the report-draft stage
curl "https://needsiq.com/api/v1/cases?productLine=PROTECTION&status=REPORT_DRAFT" \
  -H "Authorization: Bearer niq_live_..."

# Fetch one case in full
curl https://needsiq.com/api/v1/cases/CASE_ID \
  -H "Authorization: Bearer niq_live_..."

# Download the report PDF
curl https://needsiq.com/api/v1/cases/CASE_ID/report.pdf \
  -H "Authorization: Bearer niq_live_..." -o report.pdf

Notes

  • The API is read-only in v1. Case creation and generation stay in the app so the adviser review and sign-off step is preserved.
  • Every response is scoped to the key owner. There is no firm-wide read endpoint; client data stays adviser-scoped.
  • Report content is a draft for adviser review, exactly as in the app. It is not advice from NeedsIQ.

Support

Questions about the API: [email protected].