Plan Manager API

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 submit invoices to the NDIS on behalf of their participants for approval and funding which LanternPay will disburse to the relevant service provider. Additionally, the Plan Manager API will also allow Plan Managers the ability to review and approve/reject claims submitted directly to LanternPay by registered service providers.

Invoices and Claims

An invoice is a representation of the invoice data submitted by a plan manager. The invoice contains a collection of claims, which represent the line items on the invoice. The NDIS processes claims, not invoices, so an invoice can contain claims which have individual funding decisions.

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 lookup an invoice and see an invoice-level status as well as claim-level statuses, as defined below.

Invoice and Claim Statuses

Level Status Description
Invoice Draft This is a draft invoice state which has not been submitted for processing. Used to validate claims before submitting an invoice for processing.
Invoice Submitted This is the state of an invoice submitted directly to LanternPay by a Provider and at least one claim is awaiting Authorization by a Plan Manager. See claim states for further detail.
Invoice Processed This is the state of an invoice submitted via the Plan Manager API and has been processed successfully by LanternPay. See claim states for further detail.
Claim AuthorizationRequired This claim was submitted directly to LanternPay by a provider and is awaiting plan manager approval before further processing of the claim will occur.
Claim Authorized This claim has been authorized by LanternPay or a plan manager, but not yet by the NDIS.
Claim AuthorizedByProgram This claim has been authorized by the NDIS and will be paid. See Invoice and Claim Funding below for further detail.
Claim Rejected This claim has been rejected by LanternPay upon initial validation or by a plan manager. See insufficientContributionReason on the claim for the rejection reason.
Claim RejectedByProgram This claim has been rejected by the NDIS and will not be paid. See insufficientContributionReason on the claim for the rejection reason.
Claim Cancelled This claim has been cancelled and will not be processed further.

Invoice and Claim Funding

As the NDIS will sometimes pay above or below a claimed amount (e.g. a rounding discrepancy) we provide the below funding information at the invoice and claim level via the Plan Manager API to enable reconciliation of NDIS payments.

At the invoice level:

  • the totalClaimAmount field is the total value of all claims on the invoice and represents the total amount of funds requested from the NDIS.
  • the funded field is the total value of all claims where the NDIS has provided funding. If all claims are paid in full then the totalClaimAmount will equal the funded amount.

At the claim level:

  • the totalClaimAmount field is the amount of funding requested from the NDIS for an individual claim.
  • the funded field is the amount the NDIS actually paid, which could be equal to, above or under the totalClaimAmount.

See the Get an Invoice section for an example of these fields.

Authentication

All Plan Manager API requests to LanternPay require authentication using basicAuth. LanternPay will provide Sandbox and Production credentials, an API_Key and API_Secret, during onboarding. Never share your API credentials.

Additionally, LanternPay will post webhooks on some events which must be configured with authentication via a custom HTTP header. This header contains a webhook header name and value - for example: x-api-key = 123456789. This allows you to verify that the webhook came from LanternPay - you will need to provide this webhook header name and value to LanternPay during onboarding.

API Resources

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

Base URIs

All URIs in the API Resources section below are relative to these base URIs:

Environment URI Description
Sandbox https://api.planmanager.sandbox.lanternpay.com This is a pre-production environment you can use for testing.
Production https://api.planmanager.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 follow the lp:get-planmanager link relation to retrieve your plan manager resource. This resource can also be used to ensure connectivity with the Plan Manager API.

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.sandbox.lanternpay.com/"
        },
        "lp:get-planmanager": {
            "href": "https://api.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.

Get a Plan Manager

GET /planmanagers/{planManagerKey}

The Plan Manager resource contains information about the Plan Manager’s organisation. The _links property contains a list of hypermedia operations available to the plan manager, including lp:add-member and lp:get-member.

Path Parameters

Field Format Required? Description
planManagerKey UUID Mandatory This will be given to you by LanternPay.

Example Get Plan Manager Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5"
        },
        "lp:add-member": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members"
        },
        "lp:get-member": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/{membershipNumber}{?programCode}",
            "templated": true
        },
        "lp:add-biller": {
            "href": "https://api.sandbox.lanternpay.com/affiliates/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/billers"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "name": "Plan Manager Inc",
    "planManagerKey": "430b0abf-18ac-0205-3ad5-4bb4dc9659d5",
    "programs": [
        {
            "code": "ndis",
            "shortName": "NDIS",
            "longName": "National Disability Insurance Scheme",
            "membershipNumber": "123456789"
        }
    ]
}

Members

Members (i.e. participants) of the NDIS are managed by plan managers and registered with LanternPay to allow the plan manager to request funding from the NDIS on behalf of the participant. Each member has a unique memberKey and each of the member’s plans has a unique planKey which is used for various functions described below.

Add a Member

POST /planmanagers/{planManagerKey}/members

This resource can be used to create a member (i.e. participant) against the NDIS program. This is an async task and LanternPay will trigger a webhook to the URI provided in the _webhooks object when the member creation is complete. This webhook will also be triggered if the member’s details change in the future, such as plan balances, allowing you to keep your system in sync with LanternPay.

Path Parameters

Field Format Required? Description
planManagerKey UUID Mandatory This will be given to you by LanternPay.

Body Parameters

Field Format Required? Description
membershipNumber string Mandatory The membership number of the member with the program.
For example, with an NDIS participant this would be the NDIS number.
programCode string Mandatory The LanternPay code for the program. For example, NDIS.
dateOfBirth YYYY-MM-DD Mandatory The member’s date of birth.
name object Mandatory The container object for the member’s name.
See table below.
plan object Mandatory The container object for the member’s plan.
See table below.
_webhooks object Mandatory The container object for URIs to POST events to.
See table below.

Name Object Parameters

Field Format Required? Description
first string Mandatory The member’s first name.
last string Mandatory The member’s last name.

priceGuideCode Object Parameters

Field Format Required? Description
priceGuideCode string Mandatory The price guide code for the NDIS member.
Valid price guide codes are:
ACT_NSW_QLD_VIC (new as of 1st July 2019)
NT_SA_TAS_WA (new as of 1st July 2019)
ACT_NT_SA_WA (deprecated by NDIS 30th June 2019)
VIC_NSW_QLD_TAS (deprecated by NDIS 30th June 2019)
Remote
VeryRemote

_webhooks Object Parameters

Field Format Required? Description
onPlanChanged URI Mandatory The URI for LanternPay post to on a member created or changed event. This URI can include query parameters.

Example Add Member Request

{
    "membershipNumber":"123456789",
    "programCode":"ndis",
    "dateOfBirth":"1950-10-01",
    "name":{
        "first":"Sam",
        "last":"Smith"
    },
    "plan":{
        "priceGuideCode":"Remote"
    },
    "_webhooks":{
        "onPlanChanged":"https://webhook.site/0171a369-4934-4fd0-bbd1-f6f26d2a0619"
    }
}

Example Add Member Response

This is a HTTP 202 response verifying that LanternPay has received your request. The onPlanChanged webhook will be triggered once the member setup is complete.

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/232282425?programCode=ndis"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

onPlanChanged Webhook

WEBHOOK {onPlanChanged}

This webhook will trigger when a member is activated or when the member’s details change, such as name changes or plan changes. This action tells you something has changed and you should do a GET on the member using the URI in the webhook. The URI we trigger the webhook to is the URI you provided in the Add Member request.

Path Parameters

Field Format Required? Description
onPlanChanged URI Mandatory The URI you provided for the _webhooks.onPlanChanged field when you created the member.

Body Parameters

Field Format Required? Description
id UUID Mandatory A unique ID for the event.
created Unix Epoch Time Mandatory The date and time in Unix Epoch Time of the event.
data object Mandatory The container object for the webhook data.
See table below.
type string Mandatory The event type that triggered the webhook.

Data Object Parameters

Field Format Required? Description
membershipNumber string Mandatory The NDIS membership number of the member.
programCode string Mandatory The LanternPay code for the program. For example, NDIS.
memberUri URI Mandatory The link to the member resource.
planUri URI Mandatory The link to the member’s plan resource.

Example onPlanChanged Webhook

{
    "id": "437ec6ab-cda3-465b-90f2-3865d992440b",
    "created": 1518405650.883,
    "data": {
        "membershipNumber": "988028707",
        "programCode": "ndis",
        "memberUri": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/988028707?programCode=ndis",
        "planUri": "https://api.sandbox.lanternpay.com/plans/89b8bf06-2bc6-4e98-9f6e-845e5dded24a"
    },
    "type": "planmanagement.member.planchanged"
}

Get a Member

GET /planmanagers/{planManagerKey}/members/{membershipNumber}?programCode={programCode}

This resource can be used to query a member, including summary of their plan information. Links are included in the response to query all the details of the member’s plan(s).

Path Parameters

Field Format Required? Description
planManagerKey UUID Mandatory This will be given to you by LanternPay
membershipNumber string Mandatory The membership number of the member with the program.
For example, with an NDIS participant this would be the NDIS number.

Query Parameters

Field Format Required? Description
programCode string Mandatory The LanternPay code for the program. For example, NDIS.

Example Get a Member Response

The plan key (UUID) in the response can be used for other queries - see Plans section for more detail.

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/planmanagers/430b0abf-18ac-0205-3ad5-4bb4dc9659d5/members/238845545?programCode=ndis"
        },
        "lp:add-biller": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/billers"
        },
        "lp:create-invoice": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/invoices"
        },
        "lp:validate-contract": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/contracts/validate"
        },
        "lp:list-contracts": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/contracts"
        },
        "lp:list-billers": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/billers"
        },
        "lp:most-used-items": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/itemusages"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:plans": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4"
                    },
                    "lp:transaction-history": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/transactions{?fromDate,toDate}",
                        "templated": true
                    },
                    "lp:search-items": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items{?query,page}",
                        "templated": true
                    },
                    "lp:invoice-history": {
                        "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/invoices{?fromDate,toDate}",
                        "templated": true
                    }
                },
                "endDate": "2020-01-01",
                "startDate": "2019-01-01",
                "isActive": true,
                "programCode": "ndis",
                "totalBudget": {
                    "total": 14000,
                    "spent": 250,
                    "unspent": 13750,
                    "assigned": {
                        "total": 0,
                        "spent": 0,
                        "unspent": 0
                    },
                    "unassigned": 13750
                }
            }
        ]
    },
    "programs": [
        {
            "code": "ndis",
            "shortName": "NDIS",
            "longName": "National Disability Insurance Scheme"
        }
    ],
    "memberKey": "35161601-6821-41fa-8fc6-64975f0d58e4",
    "name": {
        "first": "Sam",
        "last": "Smith"
    },
    "membershipNumber": "238845545",
    "dateOfBirth": "1950-10-01"
}

Billers

A biller is an entity that will be receiving funds for services provided to a member. The service provider may be the same entity or a different entity. For example, a medical centre (i.e. the biller) might be an entity collecting funds on behalf of a pharmacist (i.e. the service provider)

LanternPay has two types of billers: a registered biller and an unregistered biller (or member biller):

  • A registered biller is a biller that has registered directly with LanternPay and has had all their details verified by LanternPay. Registered billers can submit their invoices directly to LanternPay for multiple programs (e.g. NDIS, TAC, etc) and LanternPay will route and process their invoices appropriately.
  • An unregistered biller, or a member biller, is a biller that does not have a direct relationship with LanternPay. These billers have a relationship with a plan manager/participant and LanternPay will make payments to these billers by instruction from the plan manager.

Add a Member’s Biller

POST /members/{memberKey}/billers

A member’s biller is an unregistered biller managed by the plan manager and LanternPay does not verify the details provided for this biller. The plan manager submits invoices against these billers for payment by LanternPay.

Path Parameters

Field Format Required? Description
memberKey UUID Mandatory The memberKey provided after a member is created.

Body Parameters

Field Format Required? Description
name string Mandatory The biller’s trading name.
email email address Mandatory The biller’s email that remittance advices will be sent to.
abn string Mandatory The biller’s ABN.
bankAccount object Mandatory The container object for the member’s bank account.
See table below.

bankAccount Object Parameters

Field Format Required? Description
bsb 6 digits Mandatory The 6 digit BSB for the biller’s bank account.
accountNumber 6 to 9 digits Mandatory The biller’s bank account number.
accountHolder string Mandatory The biller’s bank account name.

Example Add a Member’s Biller Request

{
	"name":"Sam's Physio",
	"email":"some@email.com",
	"abn":"12345678901",
	"bankAccount":{
		"bsb":"012345",
		"accountNumber":"123456789",
		"accountHolder":"My Bank Account"
	}
}

Example Add a Member’s Biller Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/billers/47d02cf1-dacd-0a69-374a-c6cb11d8d204"
        },
        "lp:get-billers": {
            "href": "https://api.sandbox.lanternpay.com/members/aa357b8f-39e0-4598-b0d2-6f521f0ee692/billers"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "name": "Sam's Physio",
    "email": "some@email.com",
    "abn": "12345678901",
    "bankAccount": {
        "bsb": "012345",
        "accountNumber": "123456789",
        "accountHolder": "My Bank Account"
    },
    "billerKey": "47d02cf1-dacd-0a69-374a-c6cb11d8d204"
}

Get a Member’s Biller List

GET /members/{memberKey}/billers

Use this resource to retrieve a list of member billers registeted against the member.

Path Parameters

Field Format Required? Description
memberKey UUID Mandatory The memberKey provided after a member is created.

Example Get a Member’s Biller Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/billers"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:billers": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/billers/48cf5266-3ea3-040e-3b3a-f2d355c28a87"
                    }
                },
                "version": "AAAAAAADw54=",
                "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
                "programKey": "70343e27-06be-4777-a4db-ebada96e3911",
                "name": "Sam's Physio",
                "email": "some@email.com",
                "abn": "12345678901"
            }
        ]
    }
}

Get a Biller

GET /billers/{billerKey}

Use this resource to query an individual biller. The JSON response will indicate whether this is a registered biller or a member biller.

Field Format Required? Description
billerKey UUID Mandatory The LanternPay unique key for the biller provided in the Add a Member Biller API response.

Example Get a Biller Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/billers/48cf5266-3ea3-040e-3b3a-f2d355c28a87"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
    "name": "Sam's Physio",
    "email": "some@email.com",
    "abn": "12345678901",
    "billingAddress": null,
    "isRegistered": false
}

Add a Registered Biller

POST /affiliates/{affiliateKey}/billers

Use this resource to refer an unregistered biller to LanternPay for registration. This will allow them to submit invoices directly to LanternPay for processing. This is an a-synchronous process as LanternPay must verify the biller’s details to complete registration. See onBillerRegistered webhook below for more detail.

Path Parameters

Field Format Required? Description
affiliateKey UUID Mandatory This is the same as your plan manager key, provided by LanternPay.

Body Parameters

Field Format Required? Description
affiliateBillerNumber string Optional An optional affiliate reference for the biller being referred to LanternPay.
user object Mandatory The container object for the biller’s personal details.
See table below.
organization object Mandatory The container object for the biller’s organisational details.
See table below.
payment object Mandatory The container object for the biller’s payment details.
See table below.
billingAddress object Mandatory The container object for the biller’s billing address.
See table below.
_webhooks object Mandatory The container object for URIs to POST events to.
See table below.

User Object Parameters

Field Format Required? Description
email string Mandatory The biller’s email.
firstName string Mandatory The biller’s first name.
lastName string Mandatory The biller’s last name.
phoneNumber 10 digits Mandatory The biller’s phone number.

Organization Object Parameters

Field Format Required? Description
abn string Mandatory The biller’s ABN.
tradingName string Mandatory The biller’s trading name.
registeredName string Mandatory The biller’s registered business name.

Payment Object Parameters

Field Format Required? Description
bsb 6 digits Mandatory The 6 digit BSB for the biller’s bank account.
accountNumber 6 to 9 digits Mandatory The biller’s bank account number.
accountName string Mandatory The biller’s bank account name.
emailForRemittance string Mandatory The biller’s email that remittance advices will be sent to.

billingAddress Object Parameters

Field Format Required? Description
unit string Optional The unit or apartment number.
street string Mandatory The street name.
postcode 4 digits Mandatory The post code.
state string Mandatory The state or territory code.
For example, valid Australian codes are:
QLD,NSW,ACT,VIC,TAS,NT,SA,WA
country string Mandatory The country name.

_webhooks Object Parameters

Field Format Required? Description
onBillerRegistered URI Mandatory The URI for LanternPay post to on the biller registered event. This URI can include query parameters.

Example Add a Registered Biller Request

{
    "affiliateBillerNumber":"123456789",
    "user":{
        "email":"some@email.com",
        "firstName":"Sam",
        "lastName":"Smith",
        "phoneNumber":"0412345678"
    },
    "organization":{
        "abn":"12345678901",
        "tradingName":"Sam's Trucks",
        "registeredName":"Sam's Trucks"
    },
    "payment":{
        "bsb":"012345",
        "accountNumber":"123456789",
        "accountName":"My Bank Account",
        "emailForRemittance":"Sam.Smith@lanternpay.com"
    },
    "billingAddress":{
        "unit":"Unit 1",
        "street":"742 Evergreen Terrace",
        "postcode":"2000",
        "state":"NSW",
        "country":"Australia"
    },
    "_webhooks":{
        "onBillerRegistered":"https://somedomain.com/biller-registered"
    }
}

Example Add a Registered Biller Response

This is a HTTP 202 response verifying that LanternPay has received your request. The onBillerRegistered webhook will be triggered once the registered biller setup is complete.

Accepted

onBillerRegistered Webhook

WEBHOOK {onBillerRegistered}

This webhook will trigger when a biller has completed registration.

Path Parameters

Field Format Required? Description
onBillerRegistered URI Mandatory The URI you provided for the _webhooks.onBillerRegistered field when you created the registered biller.

Body Parameters

Field Format Required? Description
id UUID Mandatory A unique ID for the event.
created Unix Epoch Time Mandatory The date and time in Unix Epoch Time the webhook was triggered.
data object Mandatory The container object for the webhook data.
See table below.
type string Mandatory The event type that triggered the webhook.

Data Object Parameters

Field Format Required? Description
affiliateBillerNumber string Mandatory The affiliate reference for the biller if provided during the Add a Registered Biller API request.
programCode string Mandatory The LanternPay code for the program. For example, NDIS.
billerKey UUID Mandatory The LanternPay unique key for the biller.

Example onBillerRegistered Webhook

{
    "id": "437ec6ab-cda3-456b-90f2-3865d992440b",
    "created": 1518405650.883, 
    "data": {
        "affiliateBillerNumber": "123456789",
        "programCode": "ndis",
        "billerKey": "486ec6ab-csc3-495b-90z2-3865d775440b"
    },
    "type": "billers.biller.registered",
}

Plans

A plan is a collection of service bookings containing items, budgets and date ranges for a member. Each plan has a unique planKey which can be queried via the API to view a detailed breakdown of the plan.

Get a Plan

GET /plans/{planKey}

Use this resource to query a member’s plan details. This contains individual plan coverages, dates and budgets which can be updated periodically. If you receive the onPlanChanged member webhook, detailed above, you should query the member’s details as well as the plan details for that member.

Path Parameters

Field Format Required? Description
planKey UUID Mandatory The plan key for the member returned in the lp:links _links:self section of the Get a Member response.

Example Get a Plan Response

Note: under budget the assigned field represents funds that are reserved (including total, spent and unspent) under a contract - see Contracts for more information.

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "membershipNumber": "238845545",
    "programName": "NDIS",
    "coverages": [
        {
            "category": {
                "name": "Assistance with Daily Life (CORE)",
                "code": "0001"
            },
            "startDate": "2019-01-01",
            "endDate": "2020-01-01",
            "initialBudget": 10000,
            "budget": {
                "total": 10000,
                "spent": 650,
                "unspent": 9350,
                "assigned": {
                    "total": 0,
                    "spent": 0,
                    "unspent": 0
                },
                "unassigned": 9350
            },
            "programCoverageNumber": null
        },
        {
            "category": {
                "name": "Consumables (CORE)",
                "code": "0003"
            },
            "startDate": "2019-01-01",
            "endDate": "2020-01-01",
            "initialBudget": 4000,
            "budget": {
                "total": 4000,
                "spent": 0,
                "unspent": 4000,
                "assigned": {
                    "total": 0,
                    "spent": 0,
                    "unspent": 0
                },
                "unassigned": 4000
            },
            "programCoverageNumber": null
        }
    ],
    "totalFlexBudget": {
        "total": 0,
        "spent": 0,
        "unspent": 0,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 0
    },
    "totalBudget": {
        "total": 14000,
        "spent": 650,
        "unspent": 13350,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 13350
    },
    "totalStatedBudget": {
        "total": 14000,
        "spent": 650,
        "unspent": 13350,
        "assigned": {
            "total": 0,
            "spent": 0,
            "unspent": 0
        },
        "unassigned": 13350
    }
}

Get Plan Invoice History

GET /plans/{planKey}/invoices?fromDate={fromDate}&toDate={toDate}

Use this API endpoint to retrieve a list of all invoices within a specific plan’s date range. Note, this API will not return draft invoices.

Path Parameters

Field Format Required? Description
planKey UUID Mandatory The plan key returned in the Get a Member response in the lp:links _links:self section.

Query Parameters

Field Format Required? Description
fromDate YYYY-MM-DD Mandatory The first date in the search range.
toDate YYYY-MM-DD Mandatory The last date in the search range.

Example Get Plan Invoice History Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/invoices?fromDate=2019-01-01&toDate=2019-03-01"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:invoices": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/invoices/31724c23-e780-4632-b98f-16b10312ab40"
                    }
                },
                "invoiceKey": "31724c23-e780-4632-b98f-16b10312ab40",
                "submittedDate": "2019-02-06T00:00:00",
                "invoiceDate": "2019-02-06T00:00:00",
                "invoiceNumber": "227609015",
                "total": 50,
                "totalFunded": 50,
                "biller": {
                    "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
                    "name": "Sam's Physio"
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/invoices/13926cb0-d712-4896-9576-cfb4b9254468"
                    }
                },
                "invoiceKey": "13926cb0-d712-4896-9576-cfb4b9254468",
                "submittedDate": "2019-02-06T00:00:00",
                "invoiceDate": "2019-02-06T00:00:00",
                "invoiceNumber": "233805794",
                "total": 50,
                "totalFunded": 50,
                "biller": {
                    "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
                    "name": "Sam's Physio"
                }
            }
        ]
    }
}

Items

Items are individual services for a coverage that can be claimed for funding by the NDIS. Each member’s plan contains coverages that is made up of items that the member is eligible to claim against, including a price for each item.

Search Claimable Items

GET /plans/{planKey}/items?query={query}&page={page}

Use this resource to search for claimable items against a member’s plan.

Path Parameters

Field Format Required? Description
planKey UUID Mandatory The plan key for the member returned in the lp:links _links:self section of the Get a Member response.

Query Parameters

Field Format Required? Description
query string Mandatory The search term to find an item. Will match against item code, item name, item description or item price.
For example, items?query="gel" to find all items with gel in the description.
page integer Mandatory The page number of results to return. The first page is 0 and each page will show 50 results.
The response will identify how many pages of results there are from the query - see example.

Example Search Claimable Items Request

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=0&query=%22gel%22"
        },
        "lp:first": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=0&query=%22gel%22"
        },
        "lp:last": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=1&query=%22gel%22"
        },
        "lp:next": {
            "href": "https://api.sandbox.lanternpay.com/plans/7810d904-1bce-41a9-9090-4cbca40b65d4/items?page=1&query=%22gel%22"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "resultsPerPage": 50,
    "pageNumber": 0,
    "pageCount": 1,
    "results": [
        {
            "key": "bc98f13e-0b19-4a5f-98c2-fc5e689cde5e",
            "code": "03_092406057_0103_1_1",
            "name": "Continence Package B - Intermittent Mild - Annual Amount",
            "description": "3 per day intermittent catheters with gel and lubricant - annual amount.",
            "price": null,
            "priceIncludesTax": true,
            "unitOfMeasure": "Hours",
            "type": "item",
            "statePricing": {
                "act": null,
                "nsw": null,
                "nt": null,
                "qld": null,
                "sa": null,
                "tas": null,
                "vic": null,
                "wa": null
            }
        },
        {
            "key": "8b2ce849-f6c4-4c4b-90e8-bc0ca15ad458",
            "code": "03_092406059_0103_1_1",
            "name": "Continence Package D - Intermittent Higher Needs - Annual Amount",
            "description": "6 per day intermittent catheters with gel and lubricant - annual amount.",
            "price": null,
            "priceIncludesTax": true,
            "unitOfMeasure": "Hours",
            "type": "item",
            "statePricing": {
                "act": null,
                "nsw": null,
                "nt": null,
                "qld": null,
                "sa": null,
                "tas": null,
                "vic": null,
                "wa": null
            }
        },
        {
            "key": "034e806b-6020-4fb5-a227-8aa539b97a07",
            "code": "03_092406058_0103_1_1",
            "name": "Continence Package C - Intermittent Moderate - Annual Amount",
            "description": "4 per day intermittent catheters with gel and lubricant - annual amount.",
            "price": null,
            "priceIncludesTax": true,
            "unitOfMeasure": "Hours",
            "type": "item",
            "statePricing": {
                "act": null,
                "nsw": null,
                "nt": null,
                "qld": null,
                "sa": null,
                "tas": null,
                "vic": null,
                "wa": null
            }
        }
    ]
}

Get a Member’s Most Used Items

GET /members/{memberKey}/itemusages

Use this resource to pull a list of the most frequently used items for a member. This can be a useful resource to speed up the process of plan managers creating invoices for their members by showing, or pre-populating, a list of frequently used items for that member.

Path Parameters

Field Format Required? Description
memberKey UUID Mandatory The memberKey provided after a member is created.

Example Get a Member’s Most Used Items Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/members/35161601-6821-41fa-8fc6-64975f0d58e4/itemusages"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:items": [
            {
                "name": "Transitional Support",
                "description": "Transition to NDIS funding – payment of rent and utility accounts. Short term payment as per participant plan.",
                "popularity": 34,
                "code": "01_001_0101_1_1",
                "itemKey": "fc48c1e3-eab7-4989-88e4-2e12148f9113",
                "count": 5
            }
        ]
    }
}

Invoices

Service providers (for example, a Physiotherapist) issue invoices which can be submitted to LanternPay by plan managers for processing and then funding by the NDIS. As the NDIS only supports funding for individual claims (i.e. line items on an invoice) LanternPay manages the link between invoices for providers or plan managers and claims for the NDIS. Furthermore, LanternPay can route invoices to a plan manager for authorization which were submitted directly to LanternPay by a registered service provider.

See here for a full list of all invoice and claim statuses.

Create an Invoice

POST /members/{memberKey}/invoices

Use this resource to create invoices for plan managed members. This creates a draft of the invoice with LanternPay which is pre-processed to advise of any issues or errors with the invoice. A unique invoiceKey is issued when a draft invoice is created and this is used to submit the invoice (with no expiration time) - if no errors were found with the draft invoice, the lp:submit-invoice link can be used to submit the draft invoice for processing and payment.

Path Parameters

Field Format Required? Description
memberKey UUID Mandatory The memberKey provided after a member is created.

Body Parameters

Field Format Required? Description
billerKey UUID Mandatory The LanternPay unique key for the biller returned in the Get a Biller API response.
invoiceDate YYYY-MM-DD Mandatory The date of shown on the invoice.
invoiceNumber string Mandatory The invoice number or reference shown on the invoice.
claims array of objects Mandatory The container object for an array of claims on the invoice.
See table below.

Claims Object Parameters

Field Format Required? Description
lineItemId string Optional Your unique identifier for the claim line item. These are returned in the GET Payment File response to aid financial reconciliation.
itemCode string Mandatory The unique identifer for the item to be claimed.
unitPriceIncTax currency Mandatory The unit price, including tax, of the item to be claimed to two decimal places.
For example, $12.76 would be "unitPriceIncTax":"12.76"
startDate YYYY-MM-DD Mandatory The date the claimable service started.
endDate YYYY-MM-DD Mandatory The date the claimable service ended.
quantity object - see description Mandatory The quantity units to be billed. For a time duration, you should convert this to a value of the unit price rounded to 2 decimal places.
For example, for an item that is billed hourly, and the service time was 20 minutes, you should enter quanty as:
"quantity":{"units":"0.33"}

Example Create an Invoice Request

{
	"billerKey":"48cf5266-3ea3-040e-3b3a-f2d355c28a87",
	"invoiceDate":"2019-02-07",
	"invoiceNumber":"773375062",
	"claims":[
		{
			"lineItemId":"123_001",
			"itemCode":"01_001_0101_1_1",
			"unitPriceIncTax":"50.00",
	        "startDate":"2019-02-01",
	        "endDate":"2019-02-01",
	        "quantity":{
	        	"units":"1"
	        }
		},
		{
			"lineItemId":"123_002",
			"itemCode":"01_001_0101_1_1",
			"unitPriceIncTax":"100.00",
	        "startDate":"2019-02-05",
	        "endDate":"2019-02-05",
	        "quantity":{
	        	"units":"1"
	        }
		}
	]
}

Example Create an Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/2e96b44b-a468-4138-a2f5-beeb216f7b9e"
        },
        "lp:submit-invoice": {
            "href": "https://api.sandbox.lanternpay.com/invoices/2e96b44b-a468-4138-a2f5-beeb216f7b9e/submit"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "biller": {
        "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
        "name": "Sam's Physio"
    },
    "invoiceKey": "2e96b44b-a468-4138-a2f5-beeb216f7b9e",
    "invoiceDate": "2019-02-07",
    "invoiceNumber": "773375062",
    "totalClaimAmount": 150,
    "claims": [
        {
            "claimKey": "20c4421e-4c4d-437a-8adb-ade0979c5778",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "unitPriceIncTax": "50.00",
            "unitTax": 0,
            "quantity": {
                "units": "1",
                "duration": ""
            },
            "totalPrice": 50,
            "totalClaimAmount": 50,
            "funded": 50,
            "unfunded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 50,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2019-02-01",
            "serviceEndTime": "2019-02-01",
            "validationErrors": []
        },
        {
            "claimKey": "5367f1dc-aa9e-4254-8027-36c6a3912cc8",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "unitPriceIncTax": "100.00",
            "unitTax": 0,
            "quantity": {
                "units": "1",
                "duration": ""
            },
            "totalPrice": 100,
            "totalClaimAmount": 100,
            "funded": 100,
            "unfunded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "fundingSources": [
                {
                    "name": "NDIS",
                    "insufficientContributionReasons": [],
                    "contribution": 100,
                    "requiresAuthorization": false
                }
            ],
            "serviceStartTime": "2019-02-05",
            "serviceEndTime": "2019-02-05",
            "validationErrors": []
        }
    ],
    "unfunded": 0,
    "funded": 150,
    "state": {
        "value": 1,
        "displayName": "Draft"
    }
}

Submit an Invoice

POST /invoices/{invoiceKey}/submit

This resources allows draft invoices, via their invoiceKey to be submitted for processing by the NDIS. Any valid invoice submitted via the API will be sent to the NDIS for funding.

Path Parameters

Field Format Required? Description
invoiceKey UUID Mandatory The invoiceKey provided after an invoice is created.

Example Submit an Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/5b7ad0f9-262a-451a-a7cf-994e274f0c1e/submit"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "invoiceKey": "5b7ad0f9-262a-451a-a7cf-994e274f0c1e",
    "invoiceDate": "2019-02-06",
    "invoiceNumber": "903512621",
    "submittedAtUtc": "2019-02-06T01:03:26.263Z",
    "state": {
        "value": 3,
        "displayName": "Processed"
    },
    "biller": {
        "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
        "name": "Sam's Physio"
    },
    "totalClaimAmount": 50,
    "funded": 0,
    "claims": [
        {
            "claimKey": "15149be3-cd41-46f7-a69b-d781bfa96507",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "unitPriceIncTax": 50,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 50,
            "totalClaimAmount": 50,
            "funded": 0,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "Authorized"
            },
            "lineItemId": null,
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 50,
                    "requiresAuthorization": false,
                    "name": "NDIS",
                    "contractNumber": null,
                    "preauthorizationNumber": null
                }
            ],
            "serviceStartTime": "2019-02-01",
            "serviceEndTime": "2019-02-01",
            "validationErrors": []
        }
    ],
    "programCode": "ndis"
}

Get an Invoice

GET /invoices/{invoiceKey}

Use this resource to retrieve the full details of a specific invoice, via the invoiceKey returned via the API when you create a draft invoice. See here for a full list of all invoice and claim statuses.

Additionally, we have a number of invoice webhooks which trigger on certain events to provide updates of the processing and/or payment status of the claim(s) on the invoice. See Invoice Webhooks section for more information

Path Parameters

Field Format Required? Description
invoiceKey UUID Mandatory The invoiceKey provided after an invoice is created.

Example Get an Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/5b7ad0f9-262a-451a-a7cf-994e274f0c1e/submit"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "invoiceKey": "5b7ad0f9-262a-451a-a7cf-994e274f0c1e",
    "invoiceDate": "2019-02-06",
    "invoiceNumber": "903512621",
    "submittedAtUtc": "2019-02-06T01:03:26.263Z",
    "state": {
        "value": 3,
        "displayName": "Processed"
    },
    "biller": {
        "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
        "name": "Sam's Physio"
    },
    "totalClaimAmount": 50,
    "funded": 50,
    "claims": [
        {
            "claimKey": "15149be3-cd41-46f7-a69b-d781bfa96507",
            "itemCode": "01_001_0101_1_1",
            "itemName": "Transitional Support",
            "unitPriceIncTax": 50,
            "unitTax": 0,
            "quantity": {
                "units": 1,
                "duration": "0:00"
            },
            "totalPrice": 50,
            "totalClaimAmount": 50,
            "funded": 50,
            "taxCode": "FRE",
            "state": {
                "value": 5,
                "displayName": "AuthorizedByProgram"
            },
            "lineItemId": null,
            "fundingSources": [
                {
                    "insufficientContributionReasons": [],
                    "contribution": 50,
                    "requiresAuthorization": false,
                    "name": "NDIS",
                    "contractNumber": null,
                    "preauthorizationNumber": null
                }
            ],
            "serviceStartTime": "2019-02-01",
            "serviceEndTime": "2019-02-01",
            "validationErrors": []
        }
    ],
    "programCode": "ndis"
}

Authorize an Invoice

POST /invoices/{invoiceKey}/authorize

This resources allows a plan manager to authorize or reject individual claims on an invoice submitted by a registered service provider directly to LanternPay. If a service provider submits an invoice for a member with claims that are not covered under a contract (see Contracts) then it must be authorized by the member’s plan manager before LanternPay will process the claim to the NDIS.

Note: claims on an invoice can be authorized individually, and hence, can be processed and sent to the NDIS for funding individually which can result in an invoice being funded for all claims over multiple funding cycles by the NDIS.

Path Parameters

Field Format Required? Description
invoiceKey UUID Mandatory The invoiceKey provided after an invoice is created.

Body Parameters

Field Format Required? Description
claims array of objects Mandatory The container object for an array of claims to reject or authorize. All claims on a given invoice must have an authorization action performed on them before the invoice will be processed for payment.
See table below.

Claims Object Parameters

Field Format Required? Description
claimKey UUID Mandatory The UUID for the individual claim shown in the Get Invoice API response.
action string Mandatory The authorization action for the individual claim. Can be either authorize or reject.

Example Authorize an Invoice Request

{
    "claims": [
        {
            "claimKey": "51837a68-1e76-083d-155a-b3185126cebf",
            "action": "authorize"
        },
        {
            "claimKey": "ef0e8a85-5dbe-0a7b-39fd-249a36f007d0",
            "action": "authorize"
        },
        {
            "claimKey": "723347b6-3806-0792-0f9f-56a3d2fb8997",
            "action": "reject"
        }
    ]
}

Example Authorize an Invoice Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/invoices/ba47e124-7810-0c51-023b-c2f6af7ceca1/authorize"
        },
        "lp:get-invoice": {
            "href": "https://api.sandbox.lanternpay.com/invoices/ba47e124-7810-0c51-023b-c2f6af7ceca1"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

Invoice Webhooks

WEBHOOK {invoiceWebhookUri}

We have a number of invoice webhook types which will fire on certain events that indicate that some data has changed on an invoice. The different invoice webhook types are intended to give integration partners more context when doing a lookup on an invoice to determine what data might have changed and what actions may follow those changes.

The strucutre of the invoice payload, see examples to the right, is the same for each invoice webhook - the only difference is the value of the type field, described below, which indicates the event that triggered the webhook.

Path Parameters

Field Format Required Description
invoiceWebhookUri URI Mandatory The URI you provided to LanternPay during onboarding.

Body Parameters

Field Format Required Description
id UUID Mandatory A unqiue ID for the event.
created Unix Epoch Time Mandatory The date and time in Unix Epoch Time the webhook was triggered.
data object Mandatory The container object for the webhook data.
See table below.
type string Mandatory The event that triggered the webhook.
Valid webhook types are described below.

Data Object Parameters

Field Format Required Description
membershipNumber string Mandatory The NDIS membership number for the participant the invoice was raised against.
programCode string Mandatory The LanternPay program code for NDIS which is: ndis
invoiceUri URI Mandatory The link to the invoice resource. Use the Get an Invoice API operation to view the invoice and its claims.

Webhook Types

Type Event Description
claiming.invoice.processed An invoice is submitted by a plan manager via the Plan Manager API and LanternPay has completed processing of the invoice.
claiming.invoice.received An invoice is submitted by a provider directly to LanternPay and LanternPay has completed processing of the invoice.
claiming.invoice.fundingDecision The NDIS has responded to at least one claim submission on an invoice and LanternPay has processed the NDIS response for the invoice.
claiming.invoice.cancelled LanternPay has received a request to cancel one or more claims on an invoice and has completed the cancellation.
claiming.invoice.adjusted This is reserved for future use.

Example Invoice Processed Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.processed"
}

Example Invoice Received Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.received"
}

Example Invoice Funding Decision Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.fundingDecision"
}

Example Invoice Cancelled Webhook

{
    "id": "c3042c70-29ce-4c86-8e1b-310e48t8932a",
    "created": 1559604212,
    "data": {
        "membershipNumber": "123456789",
        "programCode": "ndis",
        "invoiceUri": "https://api.sandbox.lanternpay.com/invoices/44333588-2da3-487c-952e-54dd373zgd1f"
    },
    "type": "claiming.invoice.cancelled"
}

Contracts

A contract is an agreement between a member and a LanternPay registered service provider that a portion of funds from the member’s plan is reserved for that service provider. This could be a general amount which can be used for a number of different coverages or a specific amount per coverage, as defined when the contract is created.

This means that when a service provider submits an invoice directly to LanternPay and one or more of the claims on the invoice are covered under a contract for the member then those claims will be automatically approved for processing to the NDIS. Any claims not covered by a contract will be submitted to the plan manager for authorization - see Authorize an Invoice

Validate a Draft Contract

POST /members/{memberKey}/contracts/validate

Use this resource to validate a draft contract, that will not be established, to check if the proposed items are covered for the member. If the lp:create-contract link appears in the response then the draft contract is valid.

Path Parameters

Field Format Required? Description
memberKey UUID Mandatory The memberKey provided after a member is created.

Body Parameters

Field Format Required? Description
programCode string Mandatory The LanternPay code for the program. For example, NDIS.
billerKey UUID Mandatory The LanternPay unique key for the biller returned in the Get a Biller API response.
contractNumber string Optional The service provider’s or plan manager’s identifier for the contract.
startDate YYYY-MM-DD Mandatory The start date for the contract (inclusive).
endDate YYYY-MM-DD Mandatory The end date for the contract (inclusive).
budget double optional - see description The total budget for the contract.
Use this if multiple items are covered under the contract but the limit applies to the aggregate spending across all items.
If not specified, then a per-item limit must be applied by specifying either a budget or a quantity on each preauthorization.
preauthorizations array of objects Mandatory The container object for an array of preauthorizations on the contract.
If there is no contract-level budget set then any one of quantity (to two decimal places) or item-level budget must be set.
See table below.

Preauthorizations Object Parameters

Field Format Required? Description
preauthorizationNumber string Optional Your unique identifier for the preauthorization.
itemCode string Mandatory The unique identifer for the item to be claimed.
description string Mandatory The item description.
unitPrice currency Mandatory The unit price, including tax, of the item to be claimed to two decimal places.
For example, $12.76 would be "unitPrice":"12.76"

Example Validate a Draft Contract Request

{
    "programCode": "NDIS",
    "billerKey": "13cf92a3-9ed8-0464-0409-055e45137ebe",
    "startDate": "2019-05-03",
    "endDate": "2019-05-05",
    "budget": "1000",
    "preauthorizations": [
        {
            "itemCode": "01_019_0120_1_1",
            "description": "Performing essential house and/or yard activities that the participant is not able to undertake.",
            "unitPrice": "46.2"
        },
        {
            "itemCode": "01_004_0107_1_1",
            "description": "Assist participant to undertake and/or develop skills to maintain their home environment where the participant owns their own home and/or has sole or substantial responsibility for its maintenance. Includes assisting participant to do basic house and yard work.",
            "unitPrice": "44.61"
        }
    ]
}

Example Validate a Draft Contract Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/members/9e06e246-d8ef-4c0b-b5fc-ab092458e197/contracts/validate"
        },
        "lp:create-contract": {
            "href": "https://api.sandbox.lanternpay.com/members/9e06e246-d8ef-4c0b-b5fc-ab092458e197/contracts"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    }
}

Create a Contract

POST /members/{memberKey}/contracts

Use this resource to create a contract. If the contract is valid it will be established immediately. It is recommended to first validate a draft contract before creating a contract.

Path Parameters

Field Format Required? Description
memberKey UUID Mandatory The memberKey provided after a member is created.

Body Parameters

Field Format Required? Description
programCode string Mandatory The LanternPay code for the program. For example, NDIS.
billerKey UUID Mandatory The LanternPay unique key for the biller returned in the Get a Biller API response.
contractNumber string Optional The service provider’s or plan manager’s identifier for the contract.
startDate YYYY-MM-DD Mandatory The start date for the contract (inclusive).
endDate YYYY-MM-DD Mandatory The end date for the contract (inclusive).
budget double optional - see description The total budget for the contract.
Use this if multiple items are covered under the contract but the limit applies to the aggregate spending across all items.
If not specified, then a per-item limit must be applied by specifying either a budget or a quantity on each preauthorization.
preauthorizations array of objects Mandatory The container object for an array of preauthorizations on the contract.
If there is no contract-level budget set then any one of quantity (to two decimal places) or item-level budget must be set.
See table below.

Preauthorizations Object Parameters

Field Format Required? Description
preauthorizationNumber string Optional Your unique identifier for the preauthorization.
itemCode string Mandatory The unique identifer for the item to be claimed.
description string Mandatory The item description.
unitPrice currency Mandatory The unit price, including tax, of the item to be claimed to two decimal places.
For example, $12.76 would be "unitPrice":"12.76"

Example Create a Contract Request

{
    "programCode": "NDIS",
    "billerKey": "13cf92a3-9ed8-0464-0409-055e45137ebe",
    "startDate": "2019-05-03",
    "endDate": "2019-05-05",
    "budget": "1000",
    "preauthorizations": [
        {
            "itemCode": "01_019_0120_1_1",
            "description": "Performing essential house and/or yard activities that the participant is not able to undertake.",
            "unitPrice": "46.2"
        }
    ]
}

Example Create a Contract Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/members/9e06e246-d8ef-4c0b-b5fc-ab092458e197/contracts"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "contractKey": "f703a5ce-8cf1-4327-84d4-e2974035748a",
    "state": {
        "value": 1,
        "displayName": "Draft"
    },
    "biller": {
        "billerKey": "13cf92a3-9ed8-0464-0409-055e45137ebe",
        "name": "Joseph's Physio"
    },
    "startDate": "2019-05-03",
    "endDate": "2019-05-05",
    "budget": {
        "total": 1000,
        "spent": 0,
        "unspent": 1000
    },
    "contractNumber": null,
    "preauthorizations": [
        {
            "budget": {
                "total": 0,
                "spent": 0,
                "unspent": 0
            },
            "quantity": {
                "total": 0,
                "used": 0,
                "remaining": 0
            },
            "hours": {
                "total": "0:00",
                "used": "0:00",
                "remaining": "0:00"
            },
            "item": {
                "key": "e989c073-58e8-4700-9f2d-a4c88237f52f",
                "code": "01_019_0120_1_1",
                "name": "House And/Or Yard Maintenance",
                "unitPrice": 46.2
            },
            "description": "Performing essential house and/or yard activities that the participant is not able to undertake.",
            "preauthorizationNumber": null
        }
    ],
    "title": "House And/Or Yard Maintenance"
}

Terminate a Contract

POST /contracts/{contractKey}/terminate

Use this resource to terminate an existing contract for a member. The contract is terminated immediately.

Path Parameters

Field Format Required? Description
contractKey UUID Mandatory The LanternPay unique key for the contract provided when the contract is created.

Example Terminate a Contract Response

The API will respond with HTTP 200 if the terminate request is successful.

Get a Member’s Contract List

GET /members/{memberKey}/contracts

Use this resource to retrieve a list of all contracts for a member.

Path Parameters

Field Format Required? Description
memberKey UUID Mandatory The memberKey provided after a member is created.

Example Get a Member’s Contract List Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/members/9e06e246-d8ef-4c0b-b5fc-ab092458e197/contracts"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "_embedded": {
        "lp:contracts": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/contracts/4883eea9-f180-48de-821b-4b91f0ffc680"
                    },
                    "lp:terminate": {
                        "href": "https://api.sandbox.lanternpay.com/contracts/4883eea9-f180-48de-821b-4b91f0ffc680/terminate"
                    }
                },
                "state": {
                    "value": 2,
                    "displayName": "Active"
                },
                "biller": {
                    "billerKey": "13cf92a3-9ed8-0464-0409-055e45137ebe",
                    "name": "Joseph's Physio"
                },
                "startDate": "2019-05-03",
                "endDate": "2019-05-05",
                "budget": {
                    "total": 1000,
                    "spent": 0,
                    "unspent": 1000
                },
                "contractNumber": null,
                "preauthorizations": [
                    {
                        "budget": {
                            "total": 0,
                            "spent": 0,
                            "unspent": 0
                        },
                        "quantity": {
                            "total": 0,
                            "used": 0,
                            "remaining": 0
                        },
                        "hours": {
                            "total": "0:00",
                            "used": "0:00",
                            "remaining": "0:00"
                        },
                        "item": {
                            "key": "e989c073-58e8-4700-9f2d-a4c88237f52f",
                            "code": "01_019_0120_1_1",
                            "name": "House And/Or Yard Maintenance",
                            "unitPrice": 46.2
                        },
                        "description": "Performing essential house and/or yard activities that the participant is not able to undertake.",
                        "preauthorizationNumber": null
                    }
                ],
                "title": "House And/Or Yard Maintenance"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.sandbox.lanternpay.com/contracts/4c373e5f-ea6b-4ee7-94b0-994aa3519a85"
                    },
                    "lp:terminate": {
                        "href": "https://api.sandbox.lanternpay.com/contracts/4c373e5f-ea6b-4ee7-94b0-994aa3519a85/terminate"
                    }
                },
                "state": {
                    "value": 2,
                    "displayName": "Active"
                },
                "biller": {
                    "billerKey": "05911fd1-12bb-021b-26fe-e7cbcd739c8d",
                    "name": "Luke's Massage Place"
                },
                "startDate": "2019-05-03",
                "endDate": "2019-05-05",
                "budget": {
                    "total": 1000,
                    "spent": 0,
                    "unspent": 1000
                },
                "contractNumber": null,
                "preauthorizations": [
                    {
                        "budget": {
                            "total": 0,
                            "spent": 0,
                            "unspent": 0
                        },
                        "quantity": {
                            "total": 0,
                            "used": 0,
                            "remaining": 0
                        },
                        "hours": {
                            "total": "0:00",
                            "used": "0:00",
                            "remaining": "0:00"
                        },
                        "item": {
                            "key": "e989c073-58e8-4700-9f2d-a4c88237f52f",
                            "code": "01_019_0120_1_1",
                            "name": "House And/Or Yard Maintenance",
                            "unitPrice": 46.2
                        },
                        "description": "Performing essential house and/or yard activities that the participant is not able to undertake.",
                        "preauthorizationNumber": null
                    }
                ],
                "title": "House And/Or Yard Maintenance"
            }
        ]
    }
}

Get a Contract

GET /contracts/{contractKey}

Use this resource to view a specific contract for a member.

Path Parameters

Field Format Required? Description
contractKey UUID Mandatory The LanternPay unique key for the contract provided when the contract is created.

Example Get a Contract Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/contracts/f703a5ce-8cf1-4327-84d4-e2974035748a"
        },
        "lp:terminate": {
            "href": "https://api.sandbox.lanternpay.com/contracts/f703a5ce-8cf1-4327-84d4-e2974035748a/terminate"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "contractKey": "f703a5ce-8cf1-4327-84d4-e2974035748a",
    "state": {
        "value": 2,
        "displayName": "Active"
    },
    "biller": {
        "billerKey": "13cf92a3-9ed8-0464-0409-055e45137ebe"
    },
    "startDate": "2019-05-03",
    "endDate": "2019-05-05",
    "budget": {
        "total": 1000,
        "spent": 0,
        "unspent": 1000
    },
    "contractNumber": null,
    "preauthorizations": [
        {
            "budget": {
                "total": 0,
                "spent": 0,
                "unspent": 0
            },
            "quantity": {
                "total": 0,
                "used": 0,
                "remaining": 0
            },
            "hours": {
                "total": "0:00",
                "used": "0:00",
                "remaining": "0:00"
            },
            "item": {
                "key": "e989c073-58e8-4700-9f2d-a4c88237f52f",
                "code": "01_019_0120_1_1",
                "name": "House And/Or Yard Maintenance",
                "unitPrice": 46.2
            },
            "description": "Performing essential house and/or yard activities that the participant is not able to undertake.",
            "preauthorizationNumber": null
        }
    ],
    "title": "House And/Or Yard Maintenance"
}
    

Payments

Payments are funds disbursed by LanternPay to a biller for a service provided to a member. For NDIS, LanternPay requests funds from the NDIS on behalf of a plan manager and then once those funds are paid by the NDIS, LanternPay will disburse those funds to the billers as a rolled up (NET) payment.

LanternPay will also issue a remittance advice to the biller advising of the payment and a breakdown of all the invoices/claims for a particiular plan manager that made up the payment for that day.

onPaymentScheduled Webhook

WEBHOOK {onPaymentScheduled}

This webhook will trigger once per day per plan manager when a payment file is generated and sent to the bank for processing. The webhook body contains a paymentUri which can be used to retrieve a list of payments - see Get a List of Payments below.

Path Parameters

Field Format Required? Description
onPlanChanged URI Mandatory The URI you provided during plan manager onboarding.

Body Parameters

Field Format Required? Description
id UUID Mandatory A unqiue ID for the event.
created Unix Epoch Time Mandatory The date and time in Unix Epoch Time the webhook was triggered.
data object Mandatory The container object for the webhook data.
See table below.
type string Mandatory The event type that triggered the webhook.

Data Object Parameters

Field Format Required? Description
paymentUri URI Mandatory The link to be used for the Get a List of Payments API request shown below.
You may wish to store the directEntryFileUKey value in the URI to query the file at a later date.

Example onPaymentScheduled Webhook

{
    "id": "ff8ab070-0821-4e73-bbe9-fa4df9f58e84",
    "created": 1549415502,
    "data": {
        "paymentUri": "https://api.sandbox.lanternpay.com/payments?directEntryFileUKey=60c27986-0208-48ab-a3b0-0edcbac0b1bf"
    },
    "type": "settlements.payments.scheduled"
}

Get a List of Payments

GET /payments?directEntryFileUKey={directEntryFileUKey}

This resource will return a list of all payments that makes up a specific payment file. It contains a breakdown of all invoices and claims that the payment relates to, including full and part funded claims. This can be used to aid financial reconciliation for the plan manager for funds going in and out of their bank account.

Query Parameters

Field Format Required? Description
directEntryFileUKey UUID Mandatory The UUID provided in the onPaymentScheduled webhook.

Example Get a List of Payments Response

{
    "_links": {
        "self": {
            "href": "https://api.sandbox.lanternpay.com/payments?directEntryFileUKey=60c27986-0208-48ab-a3b0-0edcbac0b1bf"
        },
        "curies": {
            "name": "lp",
            "href": "https://docs.lanternpay.com/reference#{rel}",
            "templated": true
        }
    },
    "amount": 50,
    "date": "2019-02-06",
    "payments": [
        {
            "billerKey": "48cf5266-3ea3-040e-3b3a-f2d355c28a87",
            "amount": 50,
            "requestedDate": "2019-02-06",
            "paymentReference": "ndis20190206BZELNK",
            "contributions": [
                {
                    "invoiceNumber": "903512621",
                    "claimKey": "15149be3-cd41-46f7-a69b-d781bfa96507",
                    "amount": 50,
                    "memberKey": "35161601-6821-41fa-8fc6-64975f0d58e4"
                }
            ]
        }
    ]
}