Developer API

External case handoff API

Use this endpoint when CMS or another partner site needs to pass customer and matter details into nfspty AML, require the correct staff user to sign in, and then show the prefilled AML case screen.

Endpoint

POST /cgi-bin/app.cgi?r=case_handoff_api

Send JSON or form data. Authenticate with the configured prefill API key using the X-NFS-API-Key header, or an api_key field for server-to-server testing.

Required behaviour

The external system posts the case data and staff login email.
NFS creates a short-lived prefill token and returns login-aware URLs.
If the required staff email already has an account, NFS asks that exact user to sign in.
If another user is signed in, NFS force-logs them out first.
If the required staff email has no account, NFS sends them to account setup with the email and case return URL preserved.
After sign-in, the user lands on the prefilled case screen and can review/create the AML case.

Request fields

Field	Required	Description
`organization_id`	Yes	NFS organization receiving the case.
`customer_name`	Yes	Customer or entity name to prefill.
`login_email`	Recommended	Staff email that must sign in before the case is shown. Use this generic field for new integrations.
`cms_user_email`	Alias	CMS-compatible alias for `login_email`.
`customer_email`, `entity_type`, `industry`, `country`	No	Profile fields displayed on the case screen.
`expected_monthly_volume`, `source_summary`	No	Flow and source-of-funds/source-of-wealth details.
`source_system`, `external_reference`	No	Shown on the prefilled case banner and used to detect existing cases.
`cms_user_id`, `cms_username`	No	Optional CMS audit metadata carried through the handoff.

Example request

{
  "organization_id": 1,
  "source_system": "CMS",
  "external_reference": "202612XX 22BellinStreet Laverton3028 PhillipaDominiqueTullyCrane",
  "customer_name": "PhillipaDominiqueTullyCrane",
  "customer_email": "phillipadcrane@gmail.com",
  "entity_type": "Individual",
  "industry": "Conveyancing",
  "country": "Australia",
  "expected_monthly_volume": 0,
  "source_summary": "Imported from Conveyancing Management Software KYC record.",
  "login_email": "info@merndaconveyancing.com",
  "cms_user_id": "5839",
  "cms_username": "jack"
}

Example response

{
  "status": "ready",
  "redirect_url": "?r=case_new&prefill=...",
  "login_url": "?r=login&return_to=...",
  "absolute_redirect_url": "https://dev.nfspty.com/cgi-bin/app.cgi?r=case_new&prefill=...",
  "absolute_login_url": "https://dev.nfspty.com/cgi-bin/app.cgi?r=login&return_to=...",
  "required_login_email": "info@merndaconveyancing.com",
  "expires_in_minutes": 120
}

Which URL should partner sites use?

Use absolute_login_url when login_email is supplied. Use absolute_redirect_url only for trusted flows where a specific staff login is not required.