Plan Manager API 2.0

Overview

The following documentation details the Plan Manager API for LanternPay Integration Partners servicing NDIS Plan Managers. This will allow plan managers, via our Integration Partners, to retrieve plan information, service booking data and submit claims to the NDIS on behalf of their participants for approval and funding.

Service Bookings

A Service Booking is associated with an NDIS participant and contains specific information about the funding available for the participant and/or provider. A service booking can be at a category or item level, item level service bookings are for funding of specific types of claims, while category level are more general in nature, covering a wider range of support items. Service bookings also posses start and end dates, which indicate for what time period a service booking can be used.

Claims

A claim represents the line items on an invoice/a request for compensation for payment of an invoice. The NDIS processes claims, not invoices, so while LanternPay provisions for additional referencing data, we do not support the submission of whole invoices.

Claims can have a number of statuses which are described below and are applied to each claim individually. Through the Plan Manager API, a plan manager can submit a claim and receive updates on the claim status via webhooks

Claim Statuses

Level Status Description
Claim Authorized This claim has been authorized by the NDIS.
Claim Rejected This claim has been rejected by LanternPay or the NDIS. See rejectReason on the claim for the rejection reason.
Claim Cancelled This claim has been cancelled and will not be processed further.

NDIS References

When a claim has been submitted to the NDIS, the claims unique ndisReference field will be populated in the response. This reference matches what is shown in the NDIS portal for that claim and is useful when searching for a LanternPay submitted claim (for cancellations, for example)

Webhooks

Webhooks allow LanternPay to signal to the user that an event has occurred within the LanternPay platform. During onboarding, you will define API endpoints that LanternPay will deliver webhooks to for various events.

Field Description
id A unique ID per event. This allows the program to perform de-duplication in the event that the same event is signalled more than once.
LanternPay may send the same event multiple times if it fails to get positive acknowledgement of a request.
created The date and time in Unix Epoch Time of the event.
data A block of data relevant to the event. The schema of the data block will vary for given webhook types.
Typically, the data block will contain both data properties and action properties, which will contain the URI of the possible LanternPay resource actions that may be carried out as a next step of processing the webhook.
type A string defining the type of the webhook
_links a set of links indicating the set of available next operations related to this event

Webhook Standard Payload

Each webhook will have the following standard payload:

{
    "id": "{uuid}",
    "created": "{unix epoch time}",
    "data": "{data object}",
    "type": "{event type name}",
    "_links": {
        "lp:action": {
            "href": "{uri}"
        }
    }
}

Webhook Authentication

Webhooks must be configured with an authentication mode. Options are:

  • Custom HTTP Header: Webhook subscriber can configure a header Name and Value for a custom HTTP Header to be included in each webhook call back, e.g. X-API-Key: 1234
  • OAuth 2.0 Authorization: Webhook subscriber can configure OAuth details. LanternPay will obtain an access token using the client_credentials flow and include it in the Authorization header as a Bearer token. The configuration options are:
    • OAuth 2.0 Idp Authorize endpoint
    • Client Id
    • Client Secret

Asynchronous Webhook Handlers

When handling a webhook, the webhook handler should handle the request asynchronously.

This means responding very quickly with a success status code (202 Accepted is preferred). This style ensures that in the event of heavy load, networking resources are not ‘held open’ for the duration of the delay. It encourages the use of internal queueing mechanisms to ensure robust, reliable & scalable handling of requests even when under load.

Webhook Response Codes

The webhook handler may respond with one of the following HTTP status codes when LanternPay attempts to deliver a webhook. LanternPay actions for each status code are as below.

Status Code LanternPay Action
200 OK
  • Ignore response body.
  • Assume the request has been received.
  • Wait for callback.
202 Accepted (Preferred)
  • Ignore response body.
  • Assume the request has been received.
  • Wait for callback.
4xx Client Error
  • Abandon the webhook.
  • Notify LanternPay Support Staff to investigate.
5xx Server Error
  • Timeout has occurred.
  • Retry the webhook (see retry policy below).
  • If all retries fail, notify LanternPay Support staff.

Retry Policy

If a webhook fails to deliver, the retry policy will trigger as described below. In total there will be 24 attempts to deliver a webhook (the initial attempt + 23 retries) and if all webhooks fail this will trigger an alert to LanternPay support staff for investigation.

All 24 webhook delivery attempts will occur over a ~5.5 minute period, with half the retries delivered within the first ~40 seconds to cover intermittent failures with the receiver. The formula used for each retry is [(number of webhooks already sent)2 x 0.08] where 0.08 represents an 80ms delay.

Each retry will have the same value in the webhook id field. Due to the use of retries, it is strongly recommended that the webhook id field is used to prevent duplicate handling, particularly in the case where LanternPay is retrying due to a timeout, but internal program systems have successfully handled the webhook.

Webhook Delay (s) Time (s)
1 0 0
2 0.08 0.08
3 0.32 0.4
4 0.72 1.12
5 1.25 2.4
6 2 4.4
… … …
23 38.72 303.6
24 42.32 345.92

API Resources

This section below details out all the Plan Manager API endpoints and the various functionality of each.

Base URIs

Unless stated otherwise, all URIs in the API Resources section below are relative to these base URIs:

Environment URI Description
Sandbox https://api.ndis.planmanagers.sandbox.lanternpay.com This is a pre-production environment you can use for testing.
Production https://api.ndis.planmanagers.lanternpay.com This is the production environment.

Root

The root resource is the starting point for all API operations when using HATEAOS hypermedia to navigate the API. The first step is to obtain a OAuth access token and then you can navigate the API using the link relations present in the root response. This resource can also be used to ensure the API is online.

Get the API Root

GET /

The root API resource. No credentials, path, query or body parameters are required for this request.

Example Get Root Response

{
    "_links": {
        "self": {
            "href": "https://api.ndis.sandbox.lanternpay.com/"
        },
        "lp:get-planmanager": {
            "href": "https://api.ndis.sandbox.lanternpay.com/planmanagers/{planManagerKey}",
            "templated": true
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

Plan Managers

Plan managers are provided a unique planManagerKey when onboarding with LanternPay allowing them to uniquely manage their participants. Integration partners will be provided with a template for onboarding new plan managers during initial integration. The Plan Manager onboarding API} is one method of onboarding a plan manager.

Onboard a Plan Manager

POST /planmanagers/add

This starts the workflow to onboard a plan manager with LanternPay, depending on the integration options selected this will trigger an email to the defined administrative contact.

Body Parameters

Field Format Required? Description
planmanagerName String Mandatory The Business Name of the plan manager.
planmanagerAbn 11 digit ABN Mandatory The 11 digit ABN of the business, this is validated against the ABR checksum modulus.
planmanagerNumber Integer Mandatory The NDIS number of the Plan Manager.
planmanagerEmail String Mandatory The plan managers generic contact email address.
planmanagerPhone String Mandatory The plan managers phone number
planmanagerAdministrativeContact Object Mandatory The container object for the Administrative Contact for the plan manager, we recommend this be a director or manager

Administrative Contact Parameters

Field Format Required? Description
contactName String Mandatory The name of the nominated contact.
contactEmail String The email address of the nominated contact.
contactPhone String The contact phone number of the nominated contact.

Example Onboard a Plan Manager

{
    "planmanagerName": "Test Plan Manager",
    "planmanagerAbn": 60006000014,
    "planmanagerNumber": 4030000001,
    "planmanagerEmail": "test@planmanager.com",
    "planmanagerPhone": "0299998800",
    "planmanagerAdministrativeContact": 
      {
        "contactName": "Jane Smith",
        "contactEmail": "Jane@planmanager.com",
        "contactPhone": "0299998801"
      }
}

Claim

Service providers will generally issue invoices to plan managed participants, these invoices will generally contain line items, which can be submitted to the NDIS in the form of a claim. The Claims API enables the submission of claims to the NDIS.

Submit a Claim

POST /planmanagers/{planManagerKey}/participants/{participantNumber}/claim

This resource can be used to submit a claim for a participant

Path Parameters

Field Format Required? Description
planManagerKey UUID Mandatory This will be given to you by LanternPay when a Plan Manager is onboarded.
participantNumber Integer This is the participants NDIS number.

Body Parameters

Field Format Required? Description
participantNumber string Mandatory The NDIS number of the participant with the.
invoiceId String Mandatory The invoice number provided with the invoice.
lineItemId String Mandatory Your unique reference for the claim.
alternateInvoiceId String Optional An additional invoice level identifying field, we recommend using the your unique internal reference in this field.
alternateLineItemId String Optional An additional claim level identifying field, this can be used if an additional claim level reference field is required.
serviceBookingId String Mandatory The service booking number that the claim will be lodged against.
itemCode String Mandatory The NDIS Item code for the claim.
unitPrice Decimal Mandatory The unit price of the item being claimed, expressed to two decimal places, additional decimal places will be ignored (no rounding will be done).
quantity Decimal Mandatory The number of units that are being charged for, expressed to two decimal places, additional decimal places will be ignored (no rounding will be done).
taxCode NDIS Tax Codes Mandatory The NDIS tax code for the claim, see NDIS Tax Codes for valid entries.
claimType NDIS Claim Type Optional The type of claim that that is being submitted, must be a valid NDIS Claim Type.
cancellationReason Cancellation Claim Reason Conditional The cancellation claim reason code, this should only be provided when the NDIS Claim Type is "CANC", a valid Cancellation Claim Reason must be provided when the claimType is "CANC".
startDate YYYY-MM-DD Mandatory The date the claimable service started.
endDate YYYY-MM-DD Mandatory The date the claimable service ended.
abn 11 digits ABN Conditional The payee’s ABN, this is submitted with the claim to the NDIA. This field is mandatory when the payee possesses a valid ABN. If the payee does not possess a valid ABN then a valid NDIA exemption reason mnemonic should be included in the exemptionReason field. If the ABN is omitted or the ABN does not conform to the defined ABN format, then the claim will not be accepted.
exemptionReason Valid NDIS exemption mnemonic Conditional This field must be provided when an ABN is not present for a provider, a valid NDIA exemption reason mnemonic must be used when this condition is met.

NDIS Tax Codes

The NDIS Tax Codes are reporting fields defined by the NDIS to communicate the tax status of the claim. The NDIS accepts three values in this field, these are defined by the NDIS as follows:

Value Description
P1 Tax Claimable (10%)
P2 GST Free
P5 GST Out of Scope

NDIS Claim Types

The NDIS has defined a number of claim types that can be submitted to the NDIS. These mostly are used for reporting functions. It should be noted that a claim type of "CANC" is not used to cancel a previously submitted claim and is defined as a type of claim. For standard claims, this field should be left blank or omitted. The NDIS accepts the following claim types:

Value Description
CANC Cancellation. If cancellation is selected then a valid Cancellation Reason value must be provided.
REPW NDIA Required Report.
TRAN Provider Travel.
NF2F Non-Face-to-Face Services.
THLT Telehealth Supports.
IRSS Irregular SIL Supports.

Cancellation Claim Reasons

Cancellation claims reasons are required for NDIS claims when a Cancellation claim is submitted. The NDIS accepts the following cancellation reason codes:

Value Description
NSDH No show due to health reason.
NSDF No show due to family issues.
NSDT No show due to unavailability of transport.
NSDO Other

ABN Values

The NDIS requires that a valid ABN be provided whenever one is present. If a valid ABN is not present, then an ABN exemption reason will need to be supplied. The below table lists accepted values for this field:

Value Description
11 digit ABN A valid ABN for the payee. Note that this must meet the defined ABN format, if the value provided does not meet this check, then the invoice will default to REIMB
REIMB Participant Reimbursement – You are declaring that this payment request is a reimbursement to a participant for services and goods purchased in accordance with the funded supports outlined in the participants NDIS plan. By selecting this, you must be able to provide the tax invoice and other relevant documentation should the NDIA request it.
EXCLS ATO Excluded Supply – You are declaring that this payment request is being made to a supplier in connection with a supply that is excluded from the withholding tax rules. By selecting this, you are declaring that the supplier has provided you with the completed ATO form ‘Statement by Supplier’ and you are able to provide the completed form on request.

Example Claim Submission

{
    "invoiceId": "ABCD1234",
    "lineItemId": "LNE003",
    "alternateInvoiceId": "76720840-fc66-4b58-9c89-455122af39d7",
    "alternateLineItemId": "f475975d-8ee5-4f29-a969-bed2892e9c4f",
    "serviceBookingId": 12345,
    "itemCode": "05_220627230_0122_1_2",
    "unitPrice": 25.5,
    "quantity": 1.5,
    "taxCode": "P5",
    "claimType": "",
    "cancellationReason": "",
    "startDate": "2021-01-01",
    "endDate": "2021-01-01",
    "abn": 60006000014,
    "exemptionReason": ""
}

Claim Status Updated Webhook

WEBHOOK {onClaimStatusUpdated}

This webhook will trigger when the claim status is updated, this will generally be based on adjudiction or claim lifecycle events e.g. when a claim is authorized, paid or rejected.

Path Parameters

Field Format Required? Description
{onClaimStatusUpdated} URI Mandatory The URI that you provided during onboarding for the ndis.participant.claim.updated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time in Unix Epoch Time of the event.
data Schema follows the structure of an Claim Status Update
type ndis.participant.claim.updated
_links lp:webhook-error defines the URI to POST in case the webhook needs to be retried by LanternPay.
Note: this value can be null if no retry is possible. See example webhook.

Claim Status Update Parameters

Field Format Required? Description
success boolean Mandatory This will be true or false and comes from the NDIS, it indicates whether the call was successful
result Object Mandatory Lists the claim results. See Claim Results Object for more details
errors String Mandatory Lists any errors returned by the NDIS when performing the call

Claim Results Object

This lists out the claim details and adjudication results.

Field Format Required? Description
ndisReference UUID Mandatory This is the LanternPay unique reference for the claim and will appear in the NDIS portal.
claimNumber Integer Mandatory This is the NDIS ID for the claim and will be visibile in reconciliation reports or when inspecting the claim in the portal.
claimedAmount Decimal Mandatory This is the total amount funded by the NDIS
participantNumber Integer Mandatory The Participants NDIS number.
participantName String Optional The name of the participant as they are registered in the NDIS portal.
invoiceId String Mandatory Your orignally provided invoice Id.
lineItemId String Mandatory Your originally provided Line Item Id.
alternateInvoiceId String Optional Your original alternative Invoice Id, if provided.
alternateLineItemId String Optional Your original alternative line item Id, if provided.
claimStatus String Mandatory This is the status of the claim, see Claim Statuses for more details
startDate YYYY-MM-DD Mandatory The date the claimable service started.
endDate YYYY-MM-DD Mandatory The date the claimable service ended.
category String Mandatory The category of the item claimed
itemCode String Mandatory The NDIS Item code for the claim.
itemDescription String Mandatory The NDIS description for the Item code claimed.
claimType NDIS Claim Type Optional The type of claim that that is being submitted, must be a valid NDIS Claim Type.
cancellationReason Cancellation Claim Reason Conditional The cancellation claim reason code
unitPrice Decimal Mandatory The unit price of the item being claimed, expressed to two decimal places.
quantity Decimal Mandatory The number of units that are being charged for, expressed to two decimal places.
taxCode NDIS Tax Codes Mandatory The NDIS tax code for the claim.
planId Integer Conditional The plan debited to fund the claim.
serviceBookingId String Mandatory The service booking number that the claim was lodged against.
submitDate YYYY-MM-DD Mandatory The date the claim was submitted to the NDIS.
submitBy String Mandatory The individual or API application that submitted the claim.
rejectReasonCode String Conditional The reason code provided when a claim is rejected.
rejectReason String Conditional The clear text reason provided when a claim is rejected.
paidDate YYYY-MM-DD Conditional The date that the claim was paid, will only be populated for paid claims.
abn 11 digits ABN Conditional Populated with the ABN submitted with the claim, will be omitted if left blank and a valid exemption code was provided
exemptionCode Valid NDIS exemption mnemonic Conditional Pupulated when a valid exemption code is provided in the payload

Example Claim Status Updated Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "success": true,
        "result": {
          "ndisReference": "bfecb1bd-db96-4758-8d80-4222eb5ca355",
          "claimNumber": 10125329,
          "claimedAmount": 38.25,
          "participantNumber": 93991933,
          "participantName": "Joy Sunshine",
          "invoiceId": "ABCD1234",
          "lineItemId": "LNE003",
          "alternateInvoiceId": "76720840-fc66-4b58-9c89-455122af39d7",
          "alternateLineItemId": "f475975d-8ee5-4f29-a969-bed2892e9c4f",
          "claimStatus": "Authorized",
          "startDate": "2019-06-03",
          "endDate": "2019-06-03",
          "category": "HOME_MODIFICATIONS",
          "itemCode": "05_220627230_0122_1_2",
          "itemDescription": "Incontinence",
          "claimType": "",
          "cancellationReason": "",
          "unitPrice": 25.25,
          "quantity": 1.5,
          "taxCode": "P5",
          "planId": 1027034,
          "serviceBookingId": 12345,
          "submitDate": "2021-01-01",
          "submitBy": "TEST",
          "rejectReasonCode": "",
          "rejectReason": "",
          "paidDate": "2021-01-01",
          "abn": 60006000014,
          "exemptionCode": ""
        },
        "errors": [
          "error"
        ]
    },
    "type": "ndis.participant.claim.updated",
    "_links": {
        "lp:webhook-error": {
            "href": null
        }
    }
}

Plans

Plans provide plan managers with the plan start and end dates, as well as the plan id.

Retrieve a Plan

POST /planmanagers/{planmanagerKey}/participant/{participantNumber}/plan

This endpoint retrieves the details around the participants plan

Path Parameters

Field Format Required? Description
planManagerKey UUID Mandatory This will be given to you by LanternPay when a Plan Manager is onboarded.
participantNumber Integer This is the participants NDIS number.

Body Parameters

Field Format Required? Description
participantSurname String Mandatory The participants Surname. This must match the NDIS recorded surname.
participantDob YYYY-MM-DD Mandatory The participants date of birth. This must match the NDIS recorded surname.

Example Retrieve a Plan Request

{
      "participantSurname": "Sunshine",
      "participantDob": "2001-11-01"
}

Example Retrieve a Plan Response

HTTP 202

Plan Retrieved Webhook

WEBHOOK {onPlanRetrieved}

This webhook will trigger when the plan has been retrieved from the NDIS after receiving a request from the plan manager.

Path Parameters

Field Format Required? Description
{onClaimStatusUpdated} URI Mandatory The URI that you provided during onboarding for the ndis.participant.plan.retrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time in Unix Epoch Time of the event.
data Schema follows the structure of a Plan Retrieval
type ndis.participant.plan.retrieved
_links lp:webhook-error defines the URI to POST in case the webhook needs to be retried by LanternPay.
Note: this value can be null if no retry is possible. See example webhook.

Plan Retrieved Parameters

This lists the details of the plan.

Field Format Required? Description
participantNumber Integer Mandatory The NDIS number of the participant.
participantPlanId Integer Mandatory The plan id number.
planStartDate YYYY-MM-DD Mandatory The start date of the plan
planEndDate YYYY-MM-DD Mandatory The end date of the plan

Example Plan Retrieved Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
      "participantNumber": 93991933,
      "participantPlanId": 1010101,
      "planStartDate": "2020-01-31",
      "planEndDate": "2020-03-24"
      },
    "type": "ndis.participant.plan.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": null
        }
    } 
}

Service Booking Management

This collection of APIs and webhooks describe the service booking management functionality.

Create A Service Booking

POST /billers/{billerId}/member/{memberNumber}/serviceBooking

This resource allows the creation of an agency managed service booking.

Path Parameters

Field Format Required? Description
billerId UUID Mandatory LanternPay’s unique reference for the Biller.
memberNumber string Mandatory Member’s identifier, as issued by the NDIS.

Service Booking Body Parameters

Field Format Required? Description
memberNumber integer Mandatory Member’s identifier, as issued by the NDIS. Max 10 digits.
memberSurname string Mandatory Member’s surname. Max 80 chars.
dateOfBirth string Mandatory Member’s date of birth in YYYY-MM-DD format.
bookingType string Mandatory Must be ZSAG for a standard agency booking.
startDate string Mandatory Start date in YYYY-MM-DD format.
endDate string Mandatory End date in YYYY-MM-DD format.
planId integer Mandatory The member’s plan ID. Max 10 digits.
providerComments string Optional Any provider comments to be added to the service booking.

Example Create A Service Booking Request

{
    "memberNumber": 1234567890,
    "memberSurname": "Smith",
    "dateOfBirth": "YYYY-MM-DD",
    "bookingType": "ZSAG",
    "startDate": "YYYY-MM-DD",
    "endDate": "YYYY-MM-DD",
    "planId": 1234567890,
    "providerComments": "",
    "items": [
        {
            "itemCategory": "ASSISTIVE_TECHNOLOGY",
            "itemCode": "05_220627230_0122_1_2",
            "quantity": 2,
            "unitPrice": 123.45
        },
        {
            "itemCategory": "ASSISTIVE_TECHNOLOGY",
            "itemCode": "05_220627230_4444_1_2",
            "quantity": 1,
            "unitPrice": 45.85
        }
    ]
}

Create A Service Booking Response

HTTP 202

Service Booking Created

WEBHOOK {onServiceBookingCreated}

Example Service Booking Created Webhook

Edit A Service Booking

PATCH /billers/{billerId}/member/{memberNumber}/serviceBooking/{serviceBookingId}

Edit A Service Booking Response

HTTP 202

Service Booking Edited

WEBHOOK {onServiceBookingEdited}

Example Service Booking Edited Webhook

Delete A Service Booking

DEL /billers/{billerId}/member/{memberNumber}/serviceBooking/{serviceBookingId}

Delete A Service Booking Response

HTTP 202

Service Booking Deleted

WEBHOOK {onServiceBookingDeleted}

Example Service Booking Deleted Webhook

Request Service Booking List

POST /planmanagers/{planmanagerKey}/participant/{participantNumber}/serviceBookingList

This resources allows retrieval of a list of all the participant’s service bookings for a specific participant, shown in list view.

Path Parameters

Field Format Required? Description
planmanagerKey UUID Mandatory LanternPay’s unique reference for the planmanager.
participantNumber string Mandatory participant’s identifier, as issued by the NDIS.

Body Parameters

No body parameters are required for this request.

Request Service Booking List Response

HTTP 202

Service Booking List Retrieved

WEBHOOK {onServiceBookingListRetrieved}

This webhook will trigger when all of the service bookings for a specific participant have been retrieved.

Path Parameters

Field Format Required? Description
{onServiceBookingListRetrieved} URI Mandatory The URL that you provided for the onServiceBookingListRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data serviceBookings array containing Service Booking List View objects.
type ndis.participant.serviceBookingList.retrieved
_links lp:webhook-error defines the URI to POST to in case the webhook needs to be replayed by LanternPay. Note: this value can be null if no replay is possible.
lp:service-booking-updates-subscribe defines the templted URI to POST to in order to subscribe to any changes made to a service booking.

Service Booking List View Parameters

Field Format Required? Description
id integer Mandatory The service booking reference, as issued by the NDIS.
type string Mandatory The service booking type
participantNumber integer Mandatory The participant number, as issued by the NDIS.
participantName string Mandatory The participant’s full name.
startDate date
YYYY-MM-DD		 Mandatory The start date of the service booking.
endDate date
YYYY-MM-DD		 Mandatory The end date of the service booking.
submittedDate date
YYYY-MM-DD		 Mandatory The date the service booking was submitted.
createdBy string Mandatory The entity that created the service booking.
Values include: Staff, Provider, etc.
status string Mandatory The current status of the service booking.
Values include: Approved, Rejected, Deleted, Awaiting Provider Approval, etc.
virtualStatus string Mandatory Indicates whether the service booking is Active or Inactive.
participantPlanId integer Mandatory The participant’s plan reference, as issued by the NDIS.
providerComments string Mandatory Any comments associated with the service booking.

Example Service Booking List Retrieved Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "serviceBookings": [
            {
                "id": 123456,
                "type": "",
                "participantNumber": 123456,
                "participantName": "",
                "startDate": "YYYY-MM-DD",
                "endDate": "YYYY-MM-DD",
                "submittedDate": "YYYY-MM-DD",
                "createdBy": "",
                "status": "",
                "virtualStatus": "",
                "participantPlanId": 123456,
                "providerComments": ""
            },
            {
                "id": 123456,
                "type": "",
                "participantNumber": 123456,
                "participantName": "",
                "startDate": "YYYY-MM-DD",
                "endDate": "YYYY-MM-DD",
                "submittedDate": "YYYY-MM-DD",
                "createdBy": "",
                "status": "",
                "virtualStatus": "",
                "participantPlanId": 123456,
                "providerComments": ""
            }
        ]
    },
    "type": "ndis.participant.serviceBookingList.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/planmanagers/{planmanagerKey}/participant/{participantNumber}/serviceBooking/{serviceBookingId}/subscribe",
            "templated": true
        }
    }
}

Request Service Booking

POST /planmanagers/{planmanagerKey}/participant/{participantNumber}/serviceBooking/{serviceBookingId}

This resources allowes retrieval of a specific service booking, shown in detail view.

Path Parameters

Field Format Required? Description
planmanagerKey UUID Mandatory LanternPay’s unique reference for the planmanager.
participantNumber string Mandatory participant’s identifier, as issued by the NDIS.
serviceBookingId string Mandatory Service booking reference, as issued by the NDIS.

Body Parameters

No body parameters are required for this request.

Request Service Booking Response

HTTP 202

Service Booking Retrieved

WEBHOOK {onServiceBookingRetrieved}

This webhook will trigger when a specific service booking has been retrieved.

Path Parameters

Field Format Required? Description
{onServiceBookingRetrieved} URI Mandatory The URL that you provided for the onServiceBookingRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data serviceBooking object containing Service Booking Detail View data.
type ndis.participant.serviceBooking.retrieved
_links lp:webhook-error defines the URI to POST in case the webhook needs to be replayed by LanternPay. Note: this value can be null if no replay is possible.
lp:service-booking-updates-subscribe or lp:service-booking-updates-unsubscribe URIs will display depending on whether a subscription already exists or not for this service booking.

Service Booking Detail View Parameters

Field Format Required? Description
id integer Mandatory The service booking reference, as issued by the NDIS.
type string Mandatory The service booking type
participantNumber integer Mandatory The participant number, as issued by the NDIS.
participantName string Mandatory The participant’s full name.
startDate date
YYYY-MM-DD		 Mandatory The start date of the service booking.
endDate date
YYYY-MM-DD		 Mandatory The end date of the service booking.
revisedEndDate date
YYYY-MM-DD		 Mandatory The new service booking end date, if changed.
inkindProgram boolean Mandatory
status string Mandatory The current status of the service booking.
Values include: Approved, Rejected, Deleted, Awaiting Provider Approval, etc.
virtualStatus string Mandatory Indicates whether the service booking is Active or Inactive.
participantPlanId integer Mandatory The participant’s plan reference, as issued by the NDIS.
providerComments string Mandatory Any comments associated with the service booking.
items Array of Service Booking Items Mandatory All items associated with the service booking.

Service Booking Items

Field Format Required? Description
itemCategory string Mandatory The item’s category.
itemCode string Mandatory The item’s code.
itemDescription string Mandatory The item’s description.
quantity integer Mandatory The quantity of this item on the service booking.
allocatedAmount decimal (2dp) Mandatory The total amount of funds allocated to this item for this service booking.
remainingAmount decimal (2dp) Mandatory The remaining balance of funds allocated to this item for this service booking.

Example Service Booking Retrieved Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "serviceBooking": {
            "id": 123456,
            "type": "",
            "participantNumber": 123456,
            "participantName": "",
            "startDate": "YYYY-MM-DD",
            "endDate": "YYYY-MM-DD",
            "revisedEndDate": "YYYY-MM-DD",
            "inkindProgram": false,
            "status": "",
            "virtualStatus": "",
            "participantPlanId": 123456,
            "providerComments": "",
            "items": [
                {
                    "itemCategory": "ASSISTIVE_TECHNOLOGY",
                    "itemCode": "06_182488376_0111_2_2",
                    "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                    "quantity": 3,
                    "allocatedAmount": 100,
                    "remainingAmount": 0
                }
            ]
        }
    },
    "type": "ndis.participant.serviceBooking.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/planmanagers/bac723d5-4a55-4291-8c0e-67695f3d5cb0/participant/1234567890/serviceBooking/2266587419/subscribe"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/planmanagers/bac723d5-4a55-4291-8c0e-67695f3d5cb0/participant/1234567890/serviceBooking/2266587419/unsubscribe"
        }
    }
}

Service Booking Updated

WEBHOOK {onServiceBookingUpdated}

This webhook will trigger whenever a service booking has been updated.

Path Parameters

Field Format Required? Description
{onServiceBookingUpdated} URI Mandatory The URL that you provided for the onServiceBookingUpdated event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data serviceBooking object containing Service Booking Detail View data.
type ndis.participant.serviceBooking.updated
_links lp:webhook-error defines the URI to POST in case the webhook needs to be replayed by LanternPay. Note: this value can be null if no replay is possible.
lp:service-booking-updates-unsubscribe defines the URI to post to in order to delete the subscription for this service booking.

Example Service Booking Updated Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "serviceBooking": {
            "id": 123456,
            "type": "",
            "participantNumber": 123456,
            "participantName": "",
            "startDate": "YYYY-MM-DD",
            "endDate": "YYYY-MM-DD",
            "revisedEndDate": "YYYY-MM-DD",
            "inkindProgram": false,
            "status": "",
            "virtualStatus": "",
            "participantPlanId": 123456,
            "providerComments": "",
            "items": [
                {
                    "itemCategory": "ASSISTIVE_TECHNOLOGY",
                    "itemCode": "06_182488376_0111_2_2",
                    "itemDescription": "Home Modifications - Bathroom Mod - Minimal Structural Work",
                    "quantity": 3,
                    "allocatedAmount": 100,
                    "remainingAmount": 0
                }
            ]
        }
    },
    "type": "ndis.participant.serviceBooking.updated",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/planmanagers/bac723d5-4a55-4291-8c0e-67695f3d5cb0/participant/1234567890/serviceBooking/2266587419/subscribe"
        }
    }
}

Subscription Management

This section describes the API actions available to manage all NDIS Agency related notification subscriptions, including view, subscribe and unsubscribe actions.

Subscribe to Service Booking

POST /planmanagers/{planmanagerKey}/participant/{participantNumber}/serviceBooking/{serviceBookingId}/subscribe

This resource creates a subscription to a service booking’s onServiceBookingUpdated event that will trigger a webhook any time a service booking is updated.

Path Parameters

Field Format Required? Description
planmanagerKey UUID Mandatory LanternPay’s unique reference for the planmanager.
participantNumber string Mandatory participant’s identifier, as issued by the NDIS.
serviceBookingId string Mandatory Service booking reference, as issued by the NDIS.

Body Parameters

No body parameters are required for this request.

Subscribe to Service Booking Response

HTTP 202

Service Booking Subscribed

WEBHOOK {onServiceBookingSubscribed}

This webhook will trigger once the creation of the subscription to a service booking is complete.

Path Parameters

Field Format Required? Description
{onServiceBookingSubscribed} URI Mandatory The URL that you provided for the onServiceBookingSubscribed event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Contains the serviceBookingId for the service booking that has been subscribed to.
type ndis.participant.serviceBookingUpdates.subscribed
_links lp:webhook-error defines the URI to POST in case the webhook needs to be replayed by LanternPay. Note: this value can be null if no replay is possible.
lp:service-booking-updates-unsubscribe defines the URI to post to in order to delete the subscription for this service booking.

Example Service Booking Subscribed Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "serviceBookingId": 123456
    },
    "type": "ndis.participant.serviceBookingUpdates.subscribed",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/planmanagers/bac723d5-4a55-4291-8c0e-67695f3d5cb0/participant/1234567890/serviceBooking/2266587419/unsubscribe"
        }
    }
}

Unsubscribe from Service Booking

POST /planmanagers/{planmanagerKey}/participant/{participantNumber}/serviceBooking/{serviceBookingId}/unsubscribe

This resource deletes a subscription from a service booking’s onServiceBookingUpdated event, if it exists.

Path Parameters

Field Format Required? Description
planmanagerKey UUID Mandatory LanternPay’s unique reference for the planmanager.
participantNumber string Mandatory participant’s identifier, as issued by the NDIS.
serviceBookingId string Mandatory Service booking reference, as issued by the NDIS.

Body Parameters

No body parameters are required for this request.

Unsubscribe from Service Booking Response

HTTP 202

Service Booking Unsubscribed

WEBHOOK {onServiceBookingUnsubscribed}

This webhook will trigger once the deletion of the subscription to a service booking is complete.

Path Parameters

Field Format Required? Description
{onServiceBookingUnsubscribed} URI Mandatory The URL that you provided for the onServiceBookingUnsubscribed event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data Contains the serviceBookingId for the service booking subscription that has been deleted.
type ndis.participant.serviceBookingUpdates.unsubscribed
_links lp:webhook-error defines the URI to POST in case the webhook needs to be replayed by LanternPay. Note: this value can be null if no replay is possible.
lp:service-booking-updates-subscribe defines the URI to post to in order to subscribe to updates for this service booking.

Example Service Booking Unsubscribed Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "serviceBookingId": 123456
    },
    "type": "ndis.participant.serviceBookingUpdates.unsubscribed",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-subscribe": {
            "href": "https://api.ndis.lanternpay.com/planmanagers/bac723d5-4a55-4291-8c0e-67695f3d5cb0/participant/1234567890/serviceBooking/2266587419/subscribe"
        }
    }
}

Retrieve Active Subscriptions

POST /planmanagers/{planmanagerKey}/participant/{participantNumber}/serviceBookingSubscriptions

This resource allows retrieval of a list of all active subscriptions for a participant’s service bookings.

Path Parameters

Field Format Required? Description
planmanagerKey UUID Mandatory LanternPay’s unique reference for the planmanager.
participantNumber string Mandatory participant’s identifier, as issued by the NDIS.

Body Parameters

No body parameters are required for this request.

Retrieve Active Subscriptions Response

HTTP 202

Active Subscriptions Retrieved

WEBHOOK {onActiveSubscriptionsRetrieved}

This webhook will trigger once the list of all active subscriptions for this participant’s service bookings has been retrieved.

Path Parameters

Field Format Required? Description
{onActiveSubscriptionsRetrieved} URI Mandatory The URL that you provided for the onActiveSubscriptionsRetrieved event.

Webhook Body Parameters

Field Description
id A unique ID per event.
created The date and time of the event in Unix Epoch Time format.
data serviceBookingSubscriptions array containing the serviceBookingId for each service booking subscription that is active for this participant.
type ndis.participant.serviceBookingSubscriptions.retrieved
_links lp:webhook-error defines the URI to POST in case the webhook needs to be replayed by LanternPay. Note: this value can be null if no replay is possible.
lp:service-booking-updates-unsubscribe defines the templted URI to POST to in order to delete the subscription for a service booking.

Example Active Subscriptions Retrieved Webhook

{
    "id": "f1fa5bb0-1fd3-4d6d-adff-fbb90871c4f8",
    "created": 1626135961,
    "data": {
        "serviceBookingSubscriptions": [
            {
                "serviceBookingId": 123456
            },
            {
                "serviceBookingId": 654321
            }
        ]
    },
    "type": "ndis.participant.serviceBookingSubscriptions.retrieved",
    "_links": {
        "lp:webhook-error": {
            "href": "someURL"
        },
        "lp:service-booking-updates-unsubscribe": {
            "href": "https://api.ndis.lanternpay.com/planmanagers/{planmanagerKey}/participant/{participantNumber}/serviceBooking/{serviceBookingId}/unsubscribe",
            "templated": true
        }
    }
}