GOV.UK
This version is in beta - expect some breaking changes.
Lifetime ISA API
| Available in Sandbox | Yes |
|---|---|
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Available in Production | Yes |
| Production base URL | https://api.service.hmrc.gov.uk |
Overview
This API allows financial organisations to report Lifetime ISA (LISA) information to HM Revenue and Customs (HMRC) and get information about payments made by HMRC.
The API allows the financial organisation to:
- report a new investor to HMRC
- create, transfer or make changes to a LISA account
- get details of a LISA account
- report or get details of an investor life event
- request or get details of bonus payments and withdrawal charges
- get payment and debt information
Switch to version 2.0
On 12 March 2019 version 1.0 will be switched off and version 2.0 will be available in production.
If you are deploying after 12 March 2019, you should build based on version 2.0.
If you are deploying before 12 March 2019, you can continue building based on version 1.0 until that date. You must switch to version 2.0 on 12 March 2019.
Save reference numbers
When you report or get information from the API, you will get a unique reference number. You should save all reference numbers because you may need them for other API calls.
Versioning
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
Errors
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.
Testing
You can use the sandbox environment to test this API.
It does not currently support stateful behaviour, but you can use the payloads described in Resources to test specific scenarios.
You must set up a test user which is an organisation for this API using the Create Test User API.
Endpoints
/lifetime-isa/manager/{lisaManagerReferenceNumber}
Use a LISA manager reference to get a list of all available endpoints.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"lisaManagerReferenceNumber": "Z543210",
"_links":
{
"self": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}", "methods": ["GET"]},
"investors": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/investors", "methods": ["POST"]},
"accounts": [
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts", "methods": ["POST"]},
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}", "methods": ["GET"]}
],
"close account": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/close-account", "methods": ["POST"]},
"reinstate account": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/reinstate-account", "methods": ["POST"]},
"update subscription": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/update-subscription", "methods": ["POST"]},
"life events": [
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events", "methods": ["POST"]},
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/{lifeEventId}", "methods": ["GET"]}
],
"annual returns": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/annual-returns", "methods": ["POST"]},
"bonus payments": [
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions", "methods": ["POST"]},
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions/{transactionId}", "methods": ["GET"]}
],
"withdrawal charges": [
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/withdrawal-charges", "methods": ["POST"]},
{"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/withdrawal-charges/{transactionId}", "methods": ["GET"]}
],
"property purchase fund release": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/fund-releases", "methods": ["POST"]},
"property purchase extension": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/purchase-extensions", "methods": ["POST"]},
"property purchase outcome": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/purchase-outcomes", "methods": ["POST"]},
"bulk payments": {"href": "/lifetime-isa/manager/{lisaManagerReferenceNumber}/payments?startDate={startDate}&endDate={endDate}", "methods": ["GET"]},
"bulk payment breakdown": {"href": "/lifetime-isa/manager/$lisaManagerReferenceNumber/accounts/{accountId}/transactions/{transactionId}/payments", "methods": ["GET"]}
}
}
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
_links
object
optional
|
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Response |
|---|---|
Request with an invalid LISA Manager reference number lisaManagerReferenceNumber: 123456 |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/investors
Report a new LISA investor to HMRC to generate an investor ID. If the investor already exists, you will get their reference number.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"investorNINO" : "AB123456D",
"firstName" : "FirstName",
"lastName" : "LastName",
"dateOfBirth" : "1973-03-24"
}
| Name | Description |
|---|---|
|
investorNINO
string
required
|
The investor’s National Insurance number.
Must conform to the regular expression
For example: |
|
firstName
string
required
|
The investor’s first name.
Must conform to the regular expression
For example: |
|
lastName
string
required
|
The investor’s last name.
Must conform to the regular expression
For example: |
|
dateOfBirth
string
required
|
The investor’s date of birth. This cannot be in the future. Date in the format
For example: |
Response
HTTP status: 201 (Created)
{
"data": {
"investorId": "9876543210",
"message": "Investor created"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
investorId
string
required
|
The investor’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Investor created
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The investor details given do not match with HMRC’s records |
403 (Forbidden) |
INVESTOR_NOT_FOUND |
|
The investor already has a record with HMRC |
409 (Conflict) |
INVESTOR_ALREADY_EXISTS |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
Request with a valid payload and LISA Manager reference number lisaManagerReferenceNumber: Use your test user profile |
{
"investorNINO": "AA123456A",
"firstName": "First Name",
"lastName": "Last Name",
"dateOfBirth": "1985-03-25"
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"investorId": "9876543210",
"message": "Investor created"
}
}
|
Request with a valid payload and an invalid LISA Manager reference number lisaManagerReferenceNumber: 123456 |
{
"investorNINO": "AA123456A",
"firstName": "First Name",
"lastName": "Last Name",
"dateOfBirth": "1985-03-25"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
Request containing invalid and/or missing data lisaManagerReferenceNumber: Use your test user profile |
{
"investorNINO": "A1234567A",
"firstName": true,
"dateOfBirth": "25-03-1985"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/lastName"
},
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/dateOfBirth"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/investorNINO"
},
{
"code": "INVALID_DATA_TYPE",
"message": "Invalid data type has been used",
"path": "/firstName"
}
]
}
|
Request containing investor details which do not match HMRC’s records lisaManagerReferenceNumber: Use your test user profile |
{
"investorNINO": "AA111111A",
"firstName": "First Name",
"lastName": "Last Name",
"dateOfBirth": "1985-03-25"
}
|
HTTP status:
{
"code": "INVESTOR_NOT_FOUND",
"message": "The investor details given do not match with HMRC’s records"
}
|
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile |
{
"investorNINO": "AA123456A",
"firstName": "First Name",
"lastName": "Last Name",
"dateOfBirth": "1985-03-25"
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
Request containing a pre-existing investor’s details lisaManagerReferenceNumber: Use your test user profile |
{
"investorNINO": "AA222222A",
"firstName": "First Name",
"lastName": "Last Name",
"dateOfBirth": "1985-03-25"
}
|
HTTP status:
{
"code": "INVESTOR_ALREADY_EXISTS",
"message": "The investor already has a record with HMRC",
"id": "1234567890"
}
|
LISA accounts
LISA accounts resources
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts
Create a new account you’ve set up for an investor, or transfer an existing account from another LISA provider. If you’re creating a new account you’ll need to create a LISA investor first.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"investorId": "9876543210",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
{
"investorId": "9876543210",
"creationReason": "Transferred",
"accountId": "1234567891",
"firstSubscriptionDate": "2017-04-06",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
| Name | Description |
|---|---|
|
investorId
string
required
|
The investor’s ID reference number.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression
For example: |
|
creationReason
string
required
|
The reason the account was created. Limited to the following possible values: New
Transferred
Current year funds transferred
Previous year funds transferred
|
|
firstSubscriptionDate
string
required
|
The date of the first deposit into the account - if this is a transfer, use the date of deposit into the account managed by the previous provider. This cannot be in the future. Date in the format
For example: |
|
transferAccount
object
optional
|
If the creationReason is ‘Transferred’, 'Current year funds transferred', or 'Previous year funds transferred', then this is required. |
|
transferredFromAccountId
string
required
|
The previous provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression
For example: |
|
transferredFromLMRN
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
transferInDate
string
required
|
The date the account transferred from the previous provider to the new one. This cannot be in the future. Date in the format
For example: |
Response
HTTP status: 201 (Created)
{
"data": {
"accountId": "1234567890",
"message": "Account created"
},
"success": true,
"status": 201
}
{
"data": {
"accountId": "1234567891",
"message": "Account transferred"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
accountId
string
required
|
The provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Account created
Account transferred
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The investor details given do not match with HMRC’s records |
403 (Forbidden) |
INVESTOR_NOT_FOUND |
|
The investor is not eligible for a LISA account |
403 (Forbidden) |
INVESTOR_ELIGIBILITY_CHECK_FAILED |
|
You cannot create or transfer a LISA account because the investor has failed a compliance check |
403 (Forbidden) |
INVESTOR_COMPLIANCE_CHECK_FAILED |
|
The transferredFromAccountId and transferredFromLMRN given do not match an account on HMRC’s records |
403 (Forbidden) |
PREVIOUS_INVESTOR_ACCOUNT_DOES_NOT_EXIST |
|
You must give a transferredFromAccountId, transferredFromLMRN and transferInDate when the creationReason is transferred, current or previous year funds transferred |
403 (Forbidden) |
TRANSFER_ACCOUNT_DATA_NOT_PROVIDED |
|
You must only give a transferredFromAccountId, transferredFromLMRN, and transferInDate when the creationReason is transferred, current or previous year funds transferred |
403 (Forbidden) |
TRANSFER_ACCOUNT_DATA_PROVIDED |
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
This investor already has a LISA account |
409 (Conflict) |
INVESTOR_ACCOUNT_ALREADY_EXISTS |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
Create request with a valid payload and LISA Manager reference number lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Account created",
"accountId": "1234567890"
}
}
|
Transfer request with a valid payload and LISA Manager reference number lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "Transferred",
"accountId": "1234567891",
"firstSubscriptionDate": "2017-04-06",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Account transferred",
"accountId": "1234567891"
}
}
|
Transfer current year request with a valid payload and LISA Manager reference number lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "Current year funds transferred",
"accountId": "1234567892",
"firstSubscriptionDate": "2017-04-06",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Account transferred",
"accountId": "1234567892"
}
}
|
Transfer previous year request with a valid payload and LISA Manager reference number lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "Previous year funds transferred",
"accountId": "1234567893",
"firstSubscriptionDate": "2017-04-06",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Account transferred",
"accountId": "1234567893"
}
}
|
Request with a valid payload and an invalid LISA Manager reference number lisaManagerReferenceNumber: A123456 |
{
"investorId": "9876543210",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
Request containing invalid and/or missing data lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543",
"creationReason": "New",
"firstSubscriptionDate": "2011"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/firstSubscriptionDate"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/investorId"
},
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/accountId"
}
]
}
|
Request containing dates before 6 April 2017 lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "Transferred",
"accountId": "1234567890",
"firstSubscriptionDate": "2016-04-06",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2016-04-06"
}
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_DATE",
"message": "The firstSubscriptionDate cannot be before 6 April 2017",
"path": "/firstSubscriptionDate"
},
{
"code": "INVALID_DATE",
"message": "The transferInDate cannot be before 6 April 2017",
"path": "/transferAccount/transferInDate"
}
]
}
|
Request containing investor details which cannot be found lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "1234567890",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "INVESTOR_NOT_FOUND",
"message": "The investor details given do not match with HMRC’s records"
}
|
Request containing an investor who is not eligible for a LISA account lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "1234567891",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "INVESTOR_ELIGIBILITY_CHECK_FAILED",
"message": "The investor is not eligible for a LISA account"
}
|
Request containing an investor who has not passed the compliance check lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "1234567892",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "INVESTOR_COMPLIANCE_CHECK_FAILED",
"message": "You cannot create or transfer a LISA account because the investor has failed a compliance check"
}
|
Transfer request containing transfer details which cannot be found in HMRC's records lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "1234567889",
"creationReason": "Transferred",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
HTTP status:
{
"code": "PREVIOUS_INVESTOR_ACCOUNT_DOES_NOT_EXIST",
"message": "The transferredFromAccountId and transferredFromLMRN given do not match an account on HMRC’s records"
}
|
Transfer request without transfer details lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "Transferred",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "TRANSFER_ACCOUNT_DATA_NOT_PROVIDED",
"message": "You must give a transferredFromAccountId, transferredFromLMRN and transferInDate when the creationReason is transferred, current or previous year funds transferred"
}
|
Create request containing transfer details lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
HTTP status:
{
"code": "TRANSFER_ACCOUNT_DATA_PROVIDED",
"message": "You must only give a transferredFromAccountId, transferredFromLMRN, and transferInDate when the creationReason is transferred, current or previous year funds transferred"
}
|
Request containing a LISA account which has already been closed lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "0000000403",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
Request containing a LISA account which has already been cancelled lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "2000000403",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
Request containing a LISA account which has already been voided lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "1000000403",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "9876543210",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
Request for a pre-existing account lisaManagerReferenceNumber: Use your test user profile |
{
"investorId": "1234567899",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_EXISTS",
"message": "This investor already has a LISA account",
"accountId": "1234567890"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/reinstate-account
Re-open a LISA account that has been closed.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"accountId": "8765432100"
}
| Name | Description |
|---|---|
|
accountId
string
required
|
The provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression
For example: |
Response
HTTP status: 200 (OK)
{
"data": {
"accountId": "8765432100",
"message": "This account has been reinstated"
},
"success": true,
"status": 200
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
accountId
string
required
|
The provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: This account has been reinstated
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 200. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
You cannot reinstate this account because it was closed with a closure reason of transferred out |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
You cannot reinstate this account because it was closed with a closure reason of cancellation |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
You cannot reinstate this account because it is already open |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_OPEN |
|
You cannot reinstate this account because the investor has failed a compliance check |
403 (Forbidden) |
INVESTOR_COMPLIANCE_CHECK_FAILED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
Request with a valid payload, LISA Manager reference number and account ID lisaManagerReferenceNumber: Use your test user profile |
{
"accountId": "1234567890"
}
|
HTTP status:
{
"status": 200,
"success": true,
"data": {
"message": "This account has been reinstated",
"accountId": "1234567890"
}
}
|
Request with a valid payload and account ID, but an invalid LISA Manager reference number lisaManagerReferenceNumber: A12345 |
{
"accountId": "1234567890"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Request with a invalid payload lisaManagerReferenceNumber: Use your test user profile |
{
"accountId": "1234=5678"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/accountId"
}
]
}
|
Request for an account that is open or active lisaManagerReferenceNumber: Use your test user profile |
{
"accountId": "2000000403"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_OPEN",
"message": "The account already has a status of Open"
}
|
Request for an account that is closed with a closure reason as transferred out lisaManagerReferenceNumber: Use your test user profile |
{
"accountId": "0000000403"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "You cannot reinstate this account because it was closed with a closure reason of transferred out"
}
|
Request for an account that is closed with a closure reason as cancelled lisaManagerReferenceNumber: Use your test user profile |
{
"accountId": "1000000403"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "You cannot reinstate this account because it was closed with a closure reason of cancellation"
}
|
Request for an account that is closed with a closure reason as cancelled lisaManagerReferenceNumber: Use your test user profile |
{
"accountId": "3000000403"
}
|
HTTP status:
{
"code": "INVESTOR_COMPLIANCE_CHECK_FAILED",
"message": "You cannot reinstate this account because the investor has failed a compliance check"
}
|
Request containing an account ID that does not exist lisaManagerReferenceNumber: Use your test user profile |
{
"accountId": "0000000404"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}
Use an account ID to get account details.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"investorId": "9876543210",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "OPEN",
"subscriptionStatus": "ACTIVE"
}
{
"investorId": "9876543210",
"creationReason": "Transferred",
"accountId": "1234567891",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "OPEN",
"subscriptionStatus": "AVAILABLE",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
| Name | Description |
|---|---|
|
investorId
string
required
|
The investor’s ID reference number.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression
For example: |
|
creationReason
string
required
|
The reason the account was created. Limited to the following possible values: New
Transferred
Current year funds transferred
Previous year funds transferred
Reinstated
|
|
firstSubscriptionDate
string
required
|
The date of the first deposit into the account. If this is a transfer, use the date of deposit into the account managed by the previous provider. This cannot be in the future. Date in the format
For example: |
|
accountStatus
string
required
|
The status of the account. Limited to the following possible values: OPEN
VOID
CLOSED
|
|
subscriptionStatus
string
required
|
The subscription status for the current tax year. Limited to the following possible values: AVAILABLE
ACTIVE
LOCKED
CANCELLED
VOID
|
|
accountClosureReason
string
optional
|
The reason the account was closed. Limited to the following possible values: All funds withdrawn
Cancellation
Transferred out
Voided
|
|
closureDate
string
optional
|
The date the account was closed. This cannot be in the future. Date in the format
For example: |
|
transferAccount
object
optional
|
Account transfer information. |
|
transferredFromAccountId
string
required
|
The previous provider's own unique reference number for the investor’s LISA account.
Must conform to the regular expression
For example: |
|
transferredFromLMRN
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
transferInDate
string
required
|
The date the account transferred from the previous provider to the new one. This cannot be in the future. Date in the format
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Response |
|---|---|
|
Request with a valid LISA Manager reference number and account ID (open account)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"investorId": "9876543210",
"creationReason": "New",
"accountId": "1234567890",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "OPEN",
"subscriptionStatus": "ACTIVE"
}
|
|
Request with a valid LISA Manager reference number and account ID (transferred account)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"investorId": "9876543210",
"creationReason": "Transferred",
"accountId": "1234567891",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "OPEN",
"subscriptionStatus": "AVAILABLE",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
|
Request with a valid LISA Manager reference number and account ID (Current year funds transferred)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"investorId": "9876543210",
"creationReason": "Current year funds transferred",
"accountId": "1234567892",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "OPEN",
"subscriptionStatus": "AVAILABLE",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
|
Request with a valid LISA Manager reference number and account ID (Previous year funds transferred)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"investorId": "9876543210",
"creationReason": "Previous year funds transferred",
"accountId": "1234567893",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "OPEN",
"subscriptionStatus": "AVAILABLE",
"transferAccount": {
"transferredFromAccountId": "8765432100",
"transferredFromLMRN": "Z654321",
"transferInDate": "2017-04-06"
}
}
|
|
Request with a valid LISA Manager reference number and account ID (voided account)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"accountId": "1000000200",
"investorId": "9876543210",
"creationReason": "New",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "VOID",
"subscriptionStatus": "VOID"
}
|
|
Request with a valid LISA Manager reference number and account ID (closed account)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"accountId": "2000000200",
"investorId": "9876543210",
"creationReason": "New",
"firstSubscriptionDate": "2017-04-06",
"accountStatus": "CLOSED",
"subscriptionStatus": "VOID",
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-10-25"
}
|
|
Request with a valid account ID, but an invalid LISA Manager reference number
lisaManagerReferenceNumber: 123456 |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Request with a valid LISA Manager reference number, but an invalid account ID
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Request containing an account ID that does not exist
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
|
Request with an invalid 'Accept' header
lisaManagerReferenceNumber: Use your test user profile
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/close-account
Close an account and report the reason and date.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"accountClosureReason" : "All funds withdrawn",
"closureDate" : "2017-05-20"
}
{
"accountClosureReason" : "Cancellation",
"closureDate" : "2017-05-20"
}
| Name | Description |
|---|---|
|
accountClosureReason
string
required
|
The reason the account was closed. Limited to the following possible values: All funds withdrawn
Cancellation
|
|
closureDate
string
required
|
The date the account was closed. This cannot be in the future. Date in the format
For example: |
Response
HTTP status: 200 (OK)
{
"data": {
"accountId": "1234567890",
"message": "LISA account closed"
},
"success": true,
"status": 200
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
accountId
string
required
|
The provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: LISA account closed
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 200. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
You cannot close the account with cancellation as the reason because the cancellation period is over |
403 (Forbidden) |
CANCELLATION_PERIOD_EXCEEDED |
|
You cannot close the account with all funds withdrawn as the reason because it is within the cancellation period |
403 (Forbidden) |
ACCOUNT_WITHIN_CANCELLATION_PERIOD |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
Request with a valid payload, LISA Manager reference number and account ID lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"status": 200,
"success": true,
"data": {
"message": "LISA account closed",
"accountId": "1234567890"
}
}
|
Request with a valid payload, LISA Manager reference number and account ID lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "Cancellation",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"status": 200,
"success": true,
"data": {
"message": "LISA Account Closed",
"accountId": "1234567890"
}
}
|
Request with a valid payload and account ID, but an invalid LISA Manager reference number lisaManagerReferenceNumber: A12345 |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Request with a valid payload and LISA Manager reference number, but an invalid account ID
lisaManagerReferenceNumber: Use your test user profile
|
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
Request containing invalid and/or missing data lisaManagerReferenceNumber: Use your test user profile |
{
"closureDate": "3000"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/closureDate"
},
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/accountClosureReason"
}
]
}
|
Request containing a closure date before 6 April 2017 lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-04-05"
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_DATE",
"message": "The closureDate cannot be before 6 April 2017",
"path": "/closureDate"
}
]
}
|
Request for an account that has already been voided lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
Request for an account that has already been closed lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
Request to close an account with cancellation as the reason when the cancellation period is over lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "Cancellation",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "CANCELLATION_PERIOD_EXCEEDED",
"message": "You cannot close the account with cancellation as the reason because the cancellation period is over"
}
|
Request to close an account with all funds withdrawn as the reason and it is still within the cancellation period lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "ACCOUNT_WITHIN_CANCELLATION_PERIOD",
"message": "You cannot close the account with all funds withdrawn as the reason because it is within the cancellation period"
}
|
Request containing an account ID that does not exist lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile |
{
"accountClosureReason": "All funds withdrawn",
"closureDate": "2017-05-20"
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/update-subscription
Modify the date when the first deposit was paid after a LISA account was created.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"firstSubscriptionDate" : "2017-05-20"
}
| Name | Description |
|---|---|
|
firstSubscriptionDate
string
required
|
The date of the first deposit into the account - if this is a transfer, use the date of deposit into the account managed by the previous provider. This cannot be in the future. Date in the format
For example: |
Response
HTTP status: 200 (OK)
{
"data": {
"accountId": "1234567890",
"code": "UPDATED",
"message": "Successfully updated the firstSubscriptionDate for the LISA account"
},
"success": true,
"status": 200
}
{
"data": {
"message": "Successfully updated the firstSubscriptionDate for the LISA account and changed the account status to void because the investor has another account with an earlier firstSubscriptionDate",
"code": "UPDATED_AND_ACCOUNT_VOID",
"accountId": "1234567891"
},
"success": true,
"status": 200
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
accountId
string
required
|
The provider’s own unique reference number for the investor’s LISA account.
Must conform to the regular expression |
|
code
string
required
|
A machine-readable code for the result of the API call. This is unique for each scenario. Limited to the following possible values: UPDATED
UPDATED_AND_ACCOUNT_VOID
|
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Successfully updated the firstSubscriptionDate for the LISA account
Successfully updated the firstSubscriptionDate for the LISA account and changed the account status to void because the investor has another account with an earlier firstSubscriptionDate
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 200. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
Request with a valid payload, LISA Manager reference number and account ID lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
|
HTTP status:
{
"data": {
"message": "Successfully updated the firstSubscriptionDate for the LISA account",
"code": "UPDATED",
"accountId": "1234567890"
}
"success": true,
"status": 200
}
|
Request with a valid payload, LISA Manager reference number and account ID lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"data": {
"message": "Successfully updated the firstSubscriptionDate for the LISA account and changed the account status to void because the investor has another account with an earlier firstSubscriptionDate",
"code": "UPDATED_AND_ACCOUNT_VOID",
"accountId": "1234567891"
}
"success": true,
"status": 200
}
|
Request with a valid payload and account ID, but an invalid LISA Manager reference number lisaManagerReferenceNumber: A12345 |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
Request with a valid payload and LISA Manager reference number, but an invalid and account ID lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
Request containing invalid and/or missing data lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "3000-01-01"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/firstSubscriptionDate"
}
]
}
|
Request containing a first subscription date before 6 April 2017 lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-04-05"
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_DATE",
"message": "The firstSubscriptionDate cannot be before 6 April 2017",
"path": "/firstSubscriptionDate"
}
]
}
|
Request for an account that has already been closed lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
Request for an account that has already been cancelled lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
Request for an account that has already been void lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
Request containing an account ID that does not exist lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile |
{
"firstSubscriptionDate": "2017-05-20"
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
Life events
Life events resources
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events
Report to HMRC if an investor has been diagnosed with a terminal illness or died. You need to do this to get a lifeEventId before you can request a bonus payment from HMRC.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
| Name | Description |
|---|---|
|
eventType
string
required
|
The event that has occurred and triggers eligibility for the bonus payment. Limited to the following possible values: LISA Investor Death
LISA Investor Terminal Ill Health
|
|
eventDate
string
required
|
The date the life event occurred. This cannot be in the future. Date in the format
For example: |
Response
HTTP status: 201 (Created)
{
"data": {
"lifeEventId": "1234567891",
"message": "Life event created"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
lifeEventId
string
required
|
The life event’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Life event created
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The life event conflicts with a previous life event reported |
403 (Forbidden) |
LIFE_EVENT_INAPPROPRIATE |
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
The investor’s life event has already been reported |
409 (Conflict) |
LIFE_EVENT_ALREADY_EXISTS |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
Request with a valid payload, LISA Manager reference number and account ID lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Life event created",
"lifeEventId": "1234567891"
}
}
|
Request with a valid payload and accountID, but an invalid LISA Manager reference number lisaManagerReferenceNumber: 123456 |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
Request with a valid payload and LISA Manager reference number, but an invalid account ID lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
Request containing invalid and/or missing data lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "Invalid Event Type"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/eventDate"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/eventType"
}
]
}
|
Request containing an event date before 6 April 2017 lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-05"
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_DATE",
"message": "The eventDate cannot be before 6 April 2017",
"path": "/eventDate"
}
]
}
|
Request containing a life event that conflicts with a previously reported event lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "LIFE_EVENT_INAPPROPRIATE",
"message": "The life event conflicts with a previous life event reported"
}
|
Request for an account that has already been closed lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
Request for an account that has already been cancelled lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
Request for an account that has already been void lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
Request containing an account ID that does not exist lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
Request containing an already reported event lisaManagerReferenceNumber: Use your test user profile |
{
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
|
HTTP status:
{
"code": "LIFE_EVENT_ALREADY_EXISTS",
"message": "The investor’s life event has already been reported",
"lifeEventId": "1234567891"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/annual-returns
Report details to HMRC about LISA accounts you managed in the last tax year. You can also correct a previous return of information. You cannot send or correct a return of information if the investor account is cancelled or void.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 65,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 65,
"supersede": {
"originalLifeEventId": "7890000001",
"originalEventDate": "2018-04-05"
}
}
| Name | Description |
|---|---|
|
eventDate
string
required
|
The date the return of information is sent. This cannot be in the future. Date in the format
For example: |
|
lisaManagerName
string
required
|
The name of the LISA provider.
Must conform to the regular expression
For example: |
|
taxYear
integer
required
|
The tax year for the return of information. You cannot give the current tax year. You can only send a return of information for a previous tax year. Give the year that the tax year ends in. For example, for the 2017 to 2018 tax year give 2018.
Must conform to the regular expression
For example: |
|
marketValueCash
integer
required
|
The total value of the cash LISA account. Give the value to the nearest whole pound. Do not include decimal places. For example, send 54.56 as 55. If you give a value for marketValueCash, give a value of 0 for marketValueStocksAndShares and annualSubsStocksAndShares.
Must conform to the regular expression
For example: |
|
marketValueStocksAndShares
integer
required
|
The total value of the stocks and shares LISA account. Give the value to the nearest whole pound. Do not include decimal places. For example, send 54.56 as 55. If you give a value for marketValueStocksAndShares, give a value of 0 for marketValueCash and annualSubsCash.
Must conform to the regular expression
For example: |
|
annualSubsCash
integer
required
|
The total value of subscriptions that the investor deposited into their cash LISA account during the tax year. Give the value to the nearest whole pound. Do not include decimal places. For example, send 54.56 as 55. If you give a value for annualSubsCash, give a value of 0 for marketValueStocksAndShares and annualSubsStocksAndShares.
Must conform to the regular expression
For example: |
|
annualSubsStocksAndShares
integer
required
|
The total value of subscriptions that the investor deposited into their stocks and shares LISA account during the tax year. Give the value to the nearest whole pound. Do not include decimal places. For example, send 54.56 as 55. If you give a value for annualSubsStocksAndShares, give a value of 0 for marketValueCash and annualSubsCash.
Must conform to the regular expression
For example: |
|
supersede
object
optional
|
Correct an existing return of information. |
|
originalLifeEventId
string
required
|
The lifeEventId of the original return of information affected by the correction. This is used together with the originalEventDate to make sure the right return of information is replaced.
Must conform to the regular expression |
|
originalEventDate
string
required
|
The eventDate of the original return of information affected by the correction. Date in the format
For example: |
Response
HTTP status: 201 (Created)
{
"data": {
"lifeEventId": "7890000001",
"message": "Life event created"
},
"success": true,
"status": 201
}
{
"data": {
"lifeEventId": "7890000002",
"message": "Life event superseded"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
lifeEventId
string
required
|
The life event’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Life event created
Life event superseded
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
originalLifeEventId and the originalEventDate do not match the information in the original request |
403 (Forbidden) |
SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR |
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
This life event has already been superseded |
409 (Conflict) |
SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED |
|
The investor’s life event has already been reported |
409 (Conflict) |
LIFE_EVENT_ALREADY_EXISTS |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
Successfully sent an annual return of information lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Life event created",
"lifeEventId": "7890000001"
}
}
|
Successfully corrected an annual return of information lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 65,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 65,
"supersede": {
"originalLifeEventId": "7890000001",
"originalEventDate": "2018-04-05"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Life event superseded",
"lifeEventId": "7890000002"
}
}
|
LISA manager reference number in the wrong format lisaManagerReferenceNumber: 123456 |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
Account ID in the wrong format lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
Wrong or missing data lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "May 2018",
"taxYear": "2018",
"marketValueCash": 0,
"marketValueStocksAndShares": 10.1,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_DATA_TYPE",
"message": "Invalid data type has been used",
"path": "/taxYear"
},
{
"code": "INVALID_DATA_TYPE",
"message": "Invalid data type has been used",
"path": "/marketValueStocksAndShares"
},
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/eventDate"
},
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/lisaManagerName"
}
]
}
|
A mixture of cash and stocks and shares in the same annual return lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 55,
"annualSubsStocksAndShares": 0
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "You can only give cash or stocks and shares values",
"path": "/annualSubsCash"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "You can only give cash or stocks and shares values",
"path": "/marketValueStocksAndShares"
}
]
}
|
Tax year before 2017 lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2016,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_DATE",
"message": "The taxYear cannot be before 2017",
"path": "/taxYear"
}
]
}
|
Tax year in the future lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 3000,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_DATE",
"message": "The taxYear cannot be in the future",
"path": "/taxYear"
}
]
}
|
Account cancelled lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
Account void lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
Account void lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2017-05-10",
"lisaManagerName": "ISA Manager 1",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 56,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
|
Supersede details do not match the original return of information
lisaManagerReferenceNumber: Use your test user profile
|
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 65,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 65,
"supersede": {
"originalLifeEventId": "7890000001",
"originalEventDate": "2018-04-04"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR",
"message": "originalLifeEventId and the originalEventDate do not match the information in the original request"
}
|
Account could not be found lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
Accept header is missing or invalid lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
|
Life event already superseded
lisaManagerReferenceNumber: Use your test user profile
|
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 65,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 65,
"supersede": {
"originalLifeEventId": "7890000001",
"originalEventDate": "2018-04-05"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED",
"message": "This life event has already been superseded",
"lifeEventId": "7890000002"
}
|
Life event already exists lisaManagerReferenceNumber: Use your test user profile |
{
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55
}
|
HTTP status:
{
"code": "LIFE_EVENT_ALREADY_EXISTS",
"message": "The investor’s life event has already been reported",
"lifeEventId": "7890000001"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/fund-releases
Request the release of LISA funds to buy a property. You can also correct a request by changing the withdrawal amount or property purchase date. When you make a correction, you cannot change the property details or the conveyancer reference number.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
{
"eventDate": "2017-05-05",
"withdrawalAmount": 5000.00,
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-10"
}
}
| Name | Description |
|---|---|
|
eventDate
string
required
|
This is the date of the request to release funds. This cannot be in the future. Date in the format
For example: |
|
withdrawalAmount
number
required
|
This is the amount that the investor has withdrawn from the LISA account. You can include a value up to 2 decimal places. |
|
conveyancerReference
string
optional
|
This is the reference for the conveyancer involved with the property purchase.
Must conform to the regular expression
For example: |
|
propertyDetails
object
optional
|
The details of the property that you are requesting funds to buy. |
|
nameOrNumber
string
required
|
The name or number of the property that you are requesting funds to buy.
Must conform to the regular expression
For example: |
|
postalCode
string
required
|
The postcode of the property that you are requesting funds to buy.
Must conform to the regular expression
For example: |
|
supersede
object
optional
|
Correct an existing fund release with a new eventDate and withdrawalAmount. |
|
originalLifeEventId
string
required
|
The ID of the fund release affected by the correction.
Must conform to the regular expression
For example: |
|
originalEventDate
string
required
|
The eventDate of the fund release affected by the correction. Date in the format
For example: |
Response
HTTP status: 201 (Created)
{
"data": {
"lifeEventId": "3456789000",
"message": "Fund release created"
},
"success": true,
"status": 201
}
{
"data": {
"lifeEventId": "3456789001",
"message": "Fund release superseded"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
lifeEventId
string
required
|
The fund release’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Fund release created
Fund release superseded
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a payment which is not valid |
400 (Bad Request) |
INVALID_PAYLOAD |
|
Empty nameOrNumber |
400 (Bad Request) |
BAD_REQUEST |
|
Too long nameOrNumber |
400 (Bad Request) |
BAD_REQUEST |
|
invalid nameOrNumber |
400 (Bad Request) |
BAD_REQUEST |
|
empty postalCode |
400 (Bad Request) |
BAD_REQUEST |
|
invalid postalCode |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
The account has not been open for long enough |
403 (Forbidden) |
COMPLIANCE_ERROR_ACCOUNT_NOT_OPEN_LONG_ENOUGH |
|
Another property purchase is already recorded |
403 (Forbidden) |
COMPLIANCE_ERROR_OTHER_PURCHASE_ON_RECORD |
|
originalLifeEventId and the originalEventDate do not match the information in the original request |
403 (Forbidden) |
SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR |
|
You can only change eventDate or withdrawalAmount when superseding a property purchase fund release |
403 (Forbidden) |
INVALID_DATA_PROVIDED |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
This life event has already been superseded |
409 (Conflict) |
SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED |
|
The investor’s life event has already been reported |
409 (Conflict) |
LIFE_EVENT_ALREADY_EXISTS |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
|
Fund release created
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Fund release created",
"lifeEventId": "3456789000"
}
}
|
|
Fund release superseded
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-05",
"withdrawalAmount": 5000.00,
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-10"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Fund release superseded",
"lifeEventId": "3456789001"
}
}
|
|
Invalid LISA Manager Reference Number
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Invalid Account ID
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Submission has not passed validation lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "INVALID_PAYLOAD",
"message": "Submission has not passed validation"
}
|
|
This LISA account is already closed
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
|
This LISA account is already void
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
|
This LISA account is already cancelled
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
|
Account not open long enough
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "COMPLIANCE_ERROR_ACCOUNT_NOT_OPEN_LONG_ENOUGH",
"message": "The account has not been open for long enough"
}
|
|
Other purchase on record
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "COMPLIANCE_ERROR_OTHER_PURCHASE_ON_RECORD",
"message": "Another property purchase is already recorded"
}
|
|
Supersede details do not match the original request
lisaManagerReferenceNumber: |
{
"eventDate": "2017-06-05",
"withdrawalAmount": 10000.00,
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-05"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR",
"message": "originalLifeEventId and the originalEventDate do not match the information in the original request"
}
|
|
Invalid Data Provided
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
},
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-05"
}
}
|
HTTP status:
{
"code": "INVALID_DATA_PROVIDED",
"message": "You can only change eventDate or withdrawalAmount when superseding a property purchase fund release"
}
|
|
Account ID does not exist
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
|
The fund release you are superseding has already been superseded
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-05",
"withdrawalAmount": 4000.00,
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-10"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED",
"message": "This life event has already been superseded",
"lifeEventId": "3456789001"
}
|
|
Fund release already exists
lisaManagerReferenceNumber: |
{
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
}
}
|
HTTP status:
{
"code": "LIFE_EVENT_ALREADY_EXISTS",
"message": "The investor’s life event has already been reported",
"lifeEventId": "3456789000"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/purchase-extensions
Request an extension to your request to release funds to buy a property.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
{
"eventDate": "2017-05-11",
"eventType": "Extension one",
"supersede": {
"originalEventDate": "2017-05-10",
"originalLifeEventId": "6789000001"
}
}
| Name | Description |
|---|---|
|
fundReleaseId
string
optional
|
The reference number you get when you report a fund release. Must not be provided when correcting an existing extension.
Must conform to the regular expression
For example: |
|
eventDate
string
required
|
The date the extension is requested. This cannot be in the future. Date in the format
For example: |
|
eventType
string
required
|
The type of extension. Limited to the following possible values: Extension one
Extension two
|
|
supersede
object
optional
|
Correct an existing extension. |
|
originalLifeEventId
string
required
|
The ID of the extension affected by the correction.
Must conform to the regular expression
For example: |
|
originalEventDate
string
required
|
The eventDate of the extension affected by the correction. Date in the format
For example: |
Response
HTTP status: 201 (Created)
{
"data": {
"lifeEventId": "6789000001",
"message": "Extension created"
},
"success": true,
"status": 201
}
{
"data": {
"lifeEventId": "6789000002",
"message": "Extension superseded"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
lifeEventId
string
required
|
The extension’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Extension created
Extension superseded
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
A first extension has not yet been approved |
403 (Forbidden) |
FIRST_EXTENSION_NOT_APPROVED |
|
A first extension has already been approved |
403 (Forbidden) |
FIRST_EXTENSION_ALREADY_APPROVED |
|
A second extension has already been approved |
403 (Forbidden) |
SECOND_EXTENSION_ALREADY_APPROVED |
|
originalLifeEventId and the originalEventDate do not match the information in the original request |
403 (Forbidden) |
SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
The fundReleaseId does not match HMRC’s records |
404 (Not Found) |
FUND_RELEASE_NOT_FOUND |
|
The investor’s life event has already been requested |
409 (Conflict) |
LIFE_EVENT_ALREADY_EXISTS |
|
This fund release has already been superseded |
409 (Conflict) |
FUND_RELEASE_SUPERSEDED |
|
This life event has already been superseded |
409 (Conflict) |
SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
|
First purchase extension
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Extension created",
"lifeEventId": "6789000001"
}
}
|
|
Superseded first purchase extension
lisaManagerReferenceNumber: Use your test user profile
|
{
"eventDate": "2017-05-11",
"eventType": "Extension one",
"supersede": {
"originalEventDate": "2017-05-10",
"originalLifeEventId": "6789000001"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Extension superseded",
"lifeEventId": "6789000002"
}
}
|
|
Second purchase extension
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-08-10",
"eventType": "Extension two"
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Extension created",
"lifeEventId": "6789000003"
}
}
|
|
Superseded second purchase extension
lisaManagerReferenceNumber: Use your test user profile
|
{
"eventDate": "2017-08-11",
"eventType": "Extension two",
"supersede": {
"originalEventDate": "2017-08-10",
"originalLifeEventId": "6789000003"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Extension superseded",
"lifeEventId": "6789000004"
}
}
|
|
Request with a valid payload and an invalid LISA Manager reference number
lisaManagerReferenceNumber: 123456
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Request with a valid payload and an invalid account ID
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Request containing invalid and/or missing data
lisaManagerReferenceNumber: Use your test user profile
|
{
"eventDate": "10-05-2017",
"eventType": "Extension 1"
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/eventDate"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/eventType"
},
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/fundReleaseId"
}
]
}
|
|
The LISA account is already closed
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-08-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
|
The LISA account is already cancelled
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-08-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
|
The LISA account is already void
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-08-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
|
A first extension has not yet been approved
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-08-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "FIRST_EXTENSION_NOT_APPROVED",
"message": "A first extension has not yet been approved"
}
|
|
First extension already approved
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "FIRST_EXTENSION_ALREADY_APPROVED",
"message": "A first extension has already been approved",
"lifeEventId": "6789000001"
}
|
|
Second extension already approved
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-08-10",
"eventType": "Extension two"
}
|
HTTP status:
{
"code": "SECOND_EXTENSION_ALREADY_APPROVED",
"message": "A second extension has already been approved",
"lifeEventId": "6789000003"
}
|
|
Supersede details do not match the original request
lisaManagerReferenceNumber: Use your test user profile
|
{
"eventDate": "2017-05-11",
"eventType": "Extension one",
"supersede": {
"originalEventDate": "2017-05-10",
"originalLifeEventId": "6789000001"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR",
"message": "originalLifeEventId and the originalEventDate do not match the information in the original request"
}
|
|
Account not found
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
|
Fund release not found
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "FUND_RELEASE_NOT_FOUND",
"message": "The fundReleaseId does not match HMRC’s records"
}
|
|
Extension already exists
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789001",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "LIFE_EVENT_ALREADY_EXISTS",
"message": "The investor’s life event has already been reported",
"lifeEventId": "6789000001"
}
|
|
The associated fund release has been superseded
lisaManagerReferenceNumber: Use your test user profile
|
{
"fundReleaseId": "3456789000",
"eventDate": "2017-05-10",
"eventType": "Extension one"
}
|
HTTP status:
{
"code": "FUND_RELEASE_SUPERSEDED",
"message": "This fund release has already been superseded"
"lifeEventId": "3456789001"
}
|
|
The extension you are superseding has already been superseded
lisaManagerReferenceNumber: Use your test user profile
|
{
"eventDate": "2017-05-11",
"eventType": "Extension one",
"supersede": {
"originalEventDate": "2017-05-10",
"originalLifeEventId": "6789000001"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED",
"message": "This life event has already been superseded",
"lifeEventId": "6789000002"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/purchase-outcomes
Report to HMRC if a property purchase was completed or failed.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
{
"eventDate": "2017-10-05",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersede": {
"originalLifeEventId": "5678900001",
"originalEventDate": "2017-10-10"
}
}
{
"fundReleaseId": "3456789002",
"eventDate": "2017-05-05",
"propertyPurchaseResult": "Purchase failed"
}
| Name | Description |
|---|---|
|
fundReleaseId
string
optional
|
The reference number you get when you report a fund release. Must not be provided when correcting an existing purchase outcome.
Must conform to the regular expression
For example: |
|
eventDate
string
required
|
The date the outcome of the property purchase was known. This cannot be in the future. Date in the format
For example: |
|
propertyPurchaseResult
string
required
|
Whether a property purchase was completed or failed. Limited to the following possible values: Purchase failed
Purchase completed
|
|
propertyPurchaseValue
number
optional
|
The value of the property that the investor purchased. Only include this information if the purchase was completed. You can include an amount up to 2 decimal places. |
|
supersede
object
optional
|
Correct an existing purchase outcome. |
|
originalLifeEventId
string
required
|
The ID of the purchase outcome affected by the correction.
Must conform to the regular expression
For example: |
|
originalEventDate
string
required
|
The eventDate of the purchase outcome affected by the correction. Date in the format
For example: |
Response
HTTP status: 201 (Created)
{
"data": {
"lifeEventId": "5678900001",
"message": "Purchase outcome created"
},
"success": true,
"status": 201
}
{
"data": {
"lifeEventId": "5678900002",
"message": "Purchase outcome superseded"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
lifeEventId
string
required
|
The purchase outcome’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Purchase outcome created
Purchase outcome superseded
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
originalLifeEventId and the originalEventDate do not match the information in the original request |
403 (Forbidden) |
SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
The fundReleaseId does not match HMRC’s records |
404 (Not Found) |
FUND_RELEASE_NOT_FOUND |
|
This fund release has already been superseded |
409 (Conflict) |
FUND_RELEASE_SUPERSEDED |
|
This life event has already been superseded |
409 (Conflict) |
SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED |
|
The investor’s life event has already been reported |
409 (Conflict) |
LIFE_EVENT_ALREADY_EXISTS |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
|
Successful purchase outcome lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"lifeEventId": "5678900001",
"message": "Purchase outcome created"
}
}
|
|
Purchase outcome superseded lisaManagerReferenceNumber: |
{
"eventDate": "2017-10-05",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersede": {
"originalLifeEventId": "5678900001",
"originalEventDate": "2017-10-10"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"lifeEventId": "5678900002",
"message": "Purchase outcome superseded"
}
}
|
|
Failed purchase outcome lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789002",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase failed"
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"lifeEventId": "5678900003",
"message": "Purchase outcome created"
}
}
|
|
Invalid LISA Manager Reference Number lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Invalid Account ID lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Supersede details do not match the original request lisaManagerReferenceNumber: |
{
"eventDate": "2017-10-05",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersede": {
"originalLifeEventId": "5678900000",
"originalEventDate": "2017-10-10"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR",
"message": "originalLifeEventId and the originalEventDate do not match the information in the original request"
}
|
|
Fund release not found lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
|
HTTP status:
{
"code" : "FUND_RELEASE_NOT_FOUND",
"message" : "The fundReleaseId does not match HMRC’s records"
}
|
|
Investor account not found lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
|
The purchase outcome you are superseding has already been superseded lisaManagerReferenceNumber: |
{
"eventDate": "2017-10-05",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersede": {
"originalLifeEventId": "5678900001",
"originalEventDate": "2017-10-10"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED",
"message": "This life event has already been superseded",
"lifeEventId": "5678900002"
}
|
|
Purchase outcome already exists lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
|
HTTP status:
{
"code": "LIFE_EVENT_ALREADY_EXISTS",
"message": "The investor’s life event has already been reported",
"lifeEventId": "5678900001"
}
|
|
The associated fund release has been superseded lisaManagerReferenceNumber: |
{
"fundReleaseId": "3456789000",
"eventDate": "2017-10-05",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000
}
|
HTTP status:
{
"code": "FUND_RELEASE_SUPERSEDED",
"message": "This fund release has already been superseded",
"lifeEventId": "3456789001"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/{lifeEventId}
View life event data that has been submitted to HMRC. You can view death and terminal illness, property purchase funds release, property purchase extension, property purchase outcome, and annual return of information.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
|
lifeEventId
string
required
|
The ID for the life event.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
[
{
"lifeEventId": "1234567891",
"eventType": "LISA Investor Terminal Ill Health",
"eventDate": "2017-04-20"
}
]
[
{
"lifeEventId": "7890000001",
"eventType": "Statutory Submission",
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55,
"supersededBy": "7890000002"
}
]
[
{
"lifeEventId": "3456789001",
"eventType": "Funds release",
"eventDate": "2017-05-05",
"withdrawalAmount": 5000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
},
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-10"
}
},
{
"lifeEventId": "6789000002",
"eventType": "Extension one",
"eventDate": "2017-05-11",
"fundReleaseId": "3456789001",
"supersede": {
"originalEventDate": "2017-05-10",
"originalLifeEventId": "6789000001"
}
},
{
"lifeEventId": "6789000004",
"eventType": "Extension two",
"eventDate": "2017-08-11",
"fundReleaseId": "3456789001",
"supersede": {
"originalEventDate": "2017-08-10",
"originalLifeEventId": "6789000003"
}
},
{
"lifeEventId": "5678900002",
"fundReleaseId": "3456789001",
"eventDate": "2017-06-10",
"eventType": "Purchase outcome",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersede": {
"originalLifeEventId": "5678900001",
"originalEventDate": "2017-05-05"
}
}
]
| Name | Description |
|---|---|
|
lifeEventId
string
required
|
The ID for the life event.
Must conform to the regular expression
For example: |
|
eventType
string
required
|
The type of life event. Limited to the following possible values: LISA Investor Death
LISA Investor Terminal Ill Health
Statutory Submission
Funds release
Extension one
Extension two
Purchase outcome
|
|
eventDate
string
required
|
This is the date the life event was reported. Date in the format
For example: |
|
lisaManagerName
string
optional
|
The name of the LISA provider.
Must conform to the regular expression
For example: |
|
taxYear
integer
optional
|
The tax year for the return of information. This will be the year that the tax year ends in. For example, for the 2017 to 2018 tax year it will be 2018.
Must conform to the regular expression
For example: |
|
marketValueCash
integer
optional
|
The total value that was reported for the cash LISA account.
Must conform to the regular expression
For example: |
|
marketValueStocksAndShares
integer
optional
|
The total value that was reported for the stocks and shares LISA account.
Must conform to the regular expression
For example: |
|
annualSubsCash
integer
optional
|
The total value that was reported for investor subscriptions into their cash LISA account during the tax year.
Must conform to the regular expression
For example: |
|
annualSubsStocksAndShares
integer
optional
|
The total value that was reported for investor subscriptions into their stocks and shares LISA account during the tax year.
Must conform to the regular expression
For example: |
|
withdrawalAmount
number
optional
|
This is the amount that the investor has withdrawn from the LISA account. |
|
conveyancerReference
string
optional
|
This is the reference for the conveyancer involved with the property purchase.
Must conform to the regular expression
For example: |
|
propertyDetails
object
optional
|
The details of the property that you requested funds to buy. |
|
nameOrNumber
string
required
|
The name or number of the property that you requested funds to buy.
Must conform to the regular expression
For example: |
|
postalCode
string
required
|
The postcode of the property that you requested funds to buy.
Must conform to the regular expression
For example: |
|
fundReleaseId
string
optional
|
The ID of the fund release for an extension or purchase outcome.
Must conform to the regular expression
For example: |
|
propertyPurchaseValue
number
optional
|
The value of the property that the investor purchased. Only included if the purchase was completed. |
|
propertyPurchaseResult
string
optional
|
Whether a property purchase was completed or failed. Limited to the following possible values: Purchase failed
Purchase completed
|
|
supersede
object
optional
|
Shows that a life event was corrected. |
|
originalLifeEventId
string
required
|
The ID of the life event that was corrected.
Must conform to the regular expression
For example: |
|
originalEventDate
string
required
|
The eventDate of the life event that was corrected. Date in the format
For example: |
|
supersededBy
string
optional
|
The ID of the life event that supersedes the current one.
Must conform to the regular expression
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
Enter a real lifeEventId |
404 (Not Found) |
LIFE_EVENT_NOT_FOUND |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Response |
|---|---|
|
Terminal illness life event
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "1234567891",
"eventType" : "LISA Investor Terminal Ill Health",
"eventDate" : "2017-04-20"
}
]
|
|
Annual return of information which has been superseded
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "7890000001",
"eventType": "Statutory Submission",
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 55,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 55,
"supersededBy": "7890000002"
}
]
|
|
Annual return of information which supersedes another
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "7890000002",
"eventType": "Statutory Submission",
"eventDate": "2018-04-05",
"lisaManagerName": "Company Name",
"taxYear": 2018,
"marketValueCash": 0,
"marketValueStocksAndShares": 65,
"annualSubsCash": 0,
"annualSubsStocksAndShares": 65,
"supersede": {
"originalLifeEventId": "7890000001",
"originalEventDate": "2018-04-05"
}
}
]
|
|
Funds release which has been superseded
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "3456789000",
"eventType": "Funds release",
"eventDate": "2017-05-10",
"withdrawalAmount": 4000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
},
"supersededBy": "3456789001"
}
]
|
|
Funds release which has associated data and successful outcome
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "3456789001",
"eventType": "Funds release",
"eventDate": "2017-05-05",
"withdrawalAmount": 5000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
},
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-10"
}
},
{
"lifeEventId": "6789000002",
"eventType": "Extension one",
"eventDate": "2017-05-11",
"fundReleaseId": "3456789001",
"supersede": {
"originalLifeEventId": "6789000001",
"originalEventDate": "2017-05-10"
}
},
{
"lifeEventId": "6789000004",
"eventType": "Extension two",
"eventDate": "2017-08-11",
"fundReleaseId": "3456789001",
"supersede": {
"originalLifeEventId": "6789000003",
"originalEventDate": "2017-08-10"
}
},
{
"lifeEventId": "5678900002",
"fundReleaseId": "3456789001",
"eventDate": "2017-10-10",
"eventType": "Purchase outcome",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersede": {
"originalLifeEventId": "5678900001",
"originalEventDate": "2017-10-05"
}
}
]
|
|
Funds release with failure outcome
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "3456789002",
"eventType": "Funds release",
"eventDate": "2017-05-05",
"withdrawalAmount": 5000.00,
"conveyancerReference": "CR12345-6789",
"propertyDetails": {
"nameOrNumber": "1",
"postalCode": "AA11 1AA"
},
"supersede": {
"originalLifeEventId": "3456789000",
"originalEventDate": "2017-05-10"
}
},
{
"lifeEventId": "5678900003",
"fundReleaseId": "3456789002",
"eventDate": "2017-10-10",
"eventType": "Purchase outcome",
"propertyPurchaseResult": "Purchase failed"
}
]
|
|
Purchase extension one which has been superseded
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "6789000001",
"eventType": "Extension one",
"eventDate": "2017-05-10",
"fundReleaseId": "3456789001",
"supersededBy": "6789000002"
}
]
|
|
Purchase extension one which supersedes another
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "6789000002",
"eventType": "Extension one",
"eventDate": "2017-05-11",
"fundReleaseId": "3456789001",
"supersede": {
"originalLifeEventId": "6789000001",
"originalEventDate": "2017-05-10"
}
}
]
|
|
Purchase extension two which has been superseded
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "6789000003",
"eventType": "Extension two",
"eventDate": "2017-08-10",
"fundReleaseId": "3456789001",
"supersededBy": "6789000004"
}
]
|
|
Purchase extension two which supersedes another
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "6789000004",
"eventType": "Extension two",
"eventDate": "2017-08-11",
"fundReleaseId": "3456789001",
"supersede": {
"originalLifeEventId": "6789000003",
"originalEventDate": "2017-08-10"
}
}
]
|
|
Purchase outcome which has been superseded
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "5678900001",
"eventType": "Purchase outcome",
"eventDate": "2017-10-05",
"fundReleaseId": "3456789001",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersededBy": "5678900002"
}
]
|
|
Purchase outcome which supersedes another
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "5678900002",
"eventType": "Purchase outcome",
"eventDate": "2017-10-10",
"fundReleaseId": "3456789001",
"propertyPurchaseResult": "Purchase completed",
"propertyPurchaseValue": 250000,
"supersede": {
"originalLifeEventId": "5678900001",
"originalEventDate": "2017-10-05"
}
}
]
|
|
Purchase outcome failure
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
[
{
"lifeEventId": "5678900003",
"eventType": "Purchase outcome",
"eventDate": "2017-10-10",
"fundReleaseId": "3456789002",
"propertyPurchaseResult": "Purchase failed"
}
]
|
|
lisaManagerReferenceNumber is in the wrong format
lisaManagerReferenceNumber: 123456 |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
accountId is in the wrong format
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Account not found
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
|
Life event not found
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "LIFE_EVENT_NOT_FOUND",
"message": "The lifeEventId does not match with HMRC’s records"
}
|
Withdrawal charges
Withdrawal charges resources
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/withdrawal-charges
Tell HMRC that an investor has taken money out of a LISA account without an associated life event. You can also correct a previous withdrawal charge.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 2000.00,
"withdrawalChargeAmount": 500.00,
"withdrawalChargeAmountYTD": 750.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Superseded withdrawal",
"automaticRecoveryAmount": 500.00,
"supersede": {
"originalTransactionId": "2345678901",
"originalWithdrawalChargeAmount": 250.00,
"transactionResult": 250.00,
"reason": "Additional withdrawal"
}
}
| Name | Description |
|---|---|
|
claimPeriodStartDate
string
required
|
This is the start date of the claim period for the withdrawal charge. It must be the sixth day of the month. You cannot enter a date in the future. Date in the format
For example: |
|
claimPeriodEndDate
string
required
|
This is the end date of the claim period for the withdrawal charge. It must be the fifth day of the month. It has to be the month after the claimPeriodStartDate. Date in the format
For example: |
|
withdrawalAmount
number
required
|
This is the amount that the investor has withdrawn from the LISA account. You can include a value up to 2 decimal places. |
|
withdrawalChargeAmount
number
required
|
This is the amount charged for the withdrawal. You can include a value up to 2 decimal places. If there is a charge made during withdrawal, withdrawalChargeAmount and automaticRecoveryAmount must be the same. |
|
withdrawalChargeAmountYTD
number
required
|
This is the total value of withdrawal charges reported to HMRC for the current tax year to date. You can include a value up to 2 decimal places. |
|
fundsDeductedDuringWithdrawal
boolean
required
|
This confirms if the investor was charged and funds were deducted at the time of the withdrawal. |
|
withdrawalReason
string
required
|
This is used by HMRC to decide how the withdrawal charge is processed. Limited to the following possible values: Regular withdrawal
Superseded withdrawal
|
|
automaticRecoveryAmount
number
optional
|
This is the amount HMRC can collect from the LISA manager when a withdrawal charge is due from the investor. This cannot be greater than the withdrawalChargeAmount. If there are no funds available, this value must be 0. If there is a charge made during withdrawal, automaticRecoveryAmount and withdrawalChargeAmount must be the same. |
|
supersede
object
optional
|
Correct an existing withdrawal charge. You can request an additional charge, reduce a charge, or refund a charge. |
|
originalTransactionId
string
required
|
The transactionId of the original withdrawal charge affected by the correction or recovery. This is used together with the originalWithdrawalChargeAmount to make sure the right charge is replaced.
Must conform to the regular expression
For example: |
|
originalWithdrawalChargeAmount
number
required
|
This is how much was in the withdrawalChargeAmount in the original request. You can include a value up to 2 decimal places. |
|
transactionResult
number
required
|
The amount to be added to or recovered from the original withdrawal charge. |
|
reason
string
required
|
Confirm whether an additional charge is due or whether the investor is owed some money. Limited to the following possible values: Additional withdrawal
Withdrawal reduction
Withdrawal refund
|
Response
HTTP status: 201 (Created)
{
"data": {
"transactionId": "2345678901",
"message": "Unauthorised withdrawal transaction created"
},
"success": true,
"status": 201
}
{
"data": {
"transactionId": "2345678902",
"message": "Unauthorised withdrawal transaction created - late notification"
},
"success": true,
"status": 201
}
{
"data": {
"transactionId": "2345678903",
"message": "Unauthorised withdrawal transaction superseded"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
transactionId
string
required
|
The transaction’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Unauthorised withdrawal transaction created
Unauthorised withdrawal transaction created - late notification
Unauthorised withdrawal transaction superseded
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
There is a problem with the request data |
403 (Forbidden) |
FORBIDDEN |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
originalTransactionId and the originalWithdrawalChargeAmount do not match the information in the original request |
403 (Forbidden) |
SUPERSEDED_WITHDRAWAL_CHARGE_ID_AMOUNT_MISMATCH |
|
This withdrawal charge has already been superseded |
403 (Forbidden) |
WITHDRAWAL_CHARGE_ALREADY_SUPERSEDED |
|
The calculation from your superseded withdrawal charge is incorrect |
403 (Forbidden) |
SUPERSEDED_WITHDRAWAL_CHARGE_OUTCOME_ERROR |
|
The timescale for reporting a withdrawal charge has passed. The claim period lasts for 6 years and 14 days |
403 (Forbidden) |
WITHDRAWAL_CHARGE_TIMESCALES_EXCEEDED |
|
The withdrawal charge as a percentage of the withdrawal amount is incorrect. For withdrawals made between 06/03/2020 and 05/04/2021 the withdrawal charge is 20%. For all other withdrawals it is 25%. |
403 (Forbidden) |
WITHDRAWAL_REPORTING_ERROR |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
A withdrawal charge with these details has already been requested for this investor |
409 (Conflict) |
WITHDRAWAL_CHARGE_ALREADY_EXISTS |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
|
Unauthorised withdrawal transaction created
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Unauthorised withdrawal transaction created",
"transactionId": "2345678901"
}
}
|
|
Unauthorised withdrawal transaction created - late notification
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"success": true,
"status": 201,
"data": {
"transactionId": "2345678902",
"message": "Unauthorised withdrawal transaction created - late notification"
}
}
|
|
Unauthorised withdrawal transaction superseded
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 2000.00,
"withdrawalChargeAmount": 500.00,
"withdrawalChargeAmountYTD": 750.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Superseded withdrawal",
"automaticRecoveryAmount": 500.00,
"supersede": {
"originalTransactionId": "2345678901",
"originalWithdrawalChargeAmount": 250.00,
"transactionResult": 250.00,
"reason": "Additional withdrawal"
}
}
|
HTTP status:
{
"success": true,
"status": 201,
"data": {
"transactionId": "2345678903",
"message": "Unauthorised withdrawal transaction superseded"
}
}
|
|
Invalid and/or missing data
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": 6,
"claimPeriodEndDate": "1st May",
"withdrawalAmount": 1000.001,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal.",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_DATA_TYPE",
"message": "Invalid data type has been used",
"path": "/claimPeriodStartDate"
},
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/claimPeriodEndDate"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "Amount cannot be negative, and can only have up to 2 decimal places",
"path": "/withdrawalAmount"
},
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/withdrawalChargeAmount"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/withdrawalReason"
}
]
}
|
|
Invalid LISA Manager Reference Number
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Invalid Account ID
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Invalid monetary amounts and/or invalid dates
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-05",
"claimPeriodEndDate": "2018-12-06",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 251.00
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_DATE",
"message": "The claimPeriodStartDate must be the 6th day of the month",
"path": "/claimPeriodStartDate"
},
{
"code": "INVALID_DATE",
"message": "The claimPeriodEndDate must be the 5th day of the month which occurs after the claimPeriodStartDate",
"path": "/claimPeriodEndDate"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "automaticRecoveryAmount cannot be more than withdrawalChargeAmount",
"path": "/automaticRecoveryAmount"
},
{
"code": "AMOUNT_MISMATCH",
"message": "automaticRecoveryAmount and withdrawalChargeAmount must be the same",
"path": "/automaticRecoveryAmount"
}
]
}
|
|
This LISA account is already cancelled
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
|
This LISA account is already void
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
|
A superseded withdrawal report cannot be matched to the original
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 2000.00,
"withdrawalChargeAmount": 500.00,
"withdrawalChargeAmountYTD": 750.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Superseded withdrawal",
"automaticRecoveryAmount": 500.00,
"supersede": {
"originalTransactionId": "2345678901",
"originalWithdrawalChargeAmount": 250.00,
"transactionResult": 250.00,
"reason": "Additional withdrawal"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_WITHDRAWAL_CHARGE_ID_AMOUNT_MISMATCH",
"message": "originalTransactionId and the originalWithdrawalChargeAmount do not match the information in the original request"
}
|
|
The withdrawal charge has already been superseded
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 2000.00,
"withdrawalChargeAmount": 500.00,
"withdrawalChargeAmountYTD": 750.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Superseded withdrawal",
"automaticRecoveryAmount": 500.00,
"supersede": {
"originalTransactionId": "2345678901",
"originalWithdrawalChargeAmount": 250.00,
"transactionResult": 250.00,
"reason": "Additional withdrawal"
}
}
|
HTTP status:
{
"code": "WITHDRAWAL_CHARGE_ALREADY_SUPERSEDED",
"message": "This withdrawal charge has already been superseded",
"transactionId": "2345678901"
}
|
|
The calculation from your superseded withdrawal charge is incorrect
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 2000.00,
"withdrawalChargeAmount": 500.00,
"withdrawalChargeAmountYTD": 750.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Superseded withdrawal",
"automaticRecoveryAmount": 500.00,
"supersede": {
"originalTransactionId": "2345678901",
"originalWithdrawalChargeAmount": 250.00,
"transactionResult": 250.00,
"reason": "Additional withdrawal"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_WITHDRAWAL_CHARGE_OUTCOME_ERROR",
"message": "The calculation from your superseded withdrawal charge is incorrect"
}
|
|
The withdrawal charge as a percentage of the withdrawal amount is incorrect. For withdrawals made between 06/03/2020 and 05/04/2021 the withdrawal charge is 20%. For all other withdrawals it is 25%.
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 2000.00,
"withdrawalChargeAmount": 500.00,
"withdrawalChargeAmountYTD": 750.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Superseded withdrawal",
"automaticRecoveryAmount": 500.00,
"supersede": {
"originalTransactionId": "2345678901",
"originalWithdrawalChargeAmount": 250.00,
"transactionResult": 250.00,
"reason": "Additional withdrawal"
}
}
|
HTTP status:
{
"code": "WITHDRAWAL_REPORTING_ERROR",
"message": "The withdrawal charge does not equal 25% of the withdrawal amount"
}
|
|
Account ID does not exist
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
|
The accept header is invalid
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
|
Withdrawal charge has already been reported
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"withdrawalAmount": 1000.00,
"withdrawalChargeAmount": 250.00,
"withdrawalChargeAmountYTD": 500.00,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"automaticRecoveryAmount": 250.00
}
|
HTTP status:
{
"code": "WITHDRAWAL_CHARGE_ALREADY_EXISTS",
"message": "A withdrawal charge with these details has already been requested for this investor",
"transactionId": "2345678901"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/withdrawal-charges/{transactionId}
Use an investor’s transaction ID to get a request for a withdrawal charge that has been submitted to HMRC.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
|
transactionId
string
required
|
The ID for the transaction.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"automaticRecoveryAmount": 250,
"withdrawalAmount": 1000,
"withdrawalChargeAmount": 250,
"withdrawalChargeAmountYTD": 500,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal"
}
| Name | Description |
|---|---|
|
claimPeriodStartDate
string
required
|
This is the start date of the claim period for the withdrawal charge. It must be the sixth day of the month. You cannot enter a date in the future. Date in the format
For example: |
|
claimPeriodEndDate
string
required
|
This is the end date of the claim period for the withdrawal charge. It must be the fifth day of the month. It has to be the month after the claimPeriodStartDate. Date in the format
For example: |
|
automaticRecoveryAmount
number
optional
|
This is the amount HMRC can collect from the LISA manager when there is a withdrawal charge. If there are no funds available, this value must be 0. |
|
withdrawalAmount
number
required
|
This is the amount that the investor has withdrawn from the LISA account. |
|
withdrawalChargeAmount
number
required
|
This is the amount charged for the withdrawal. |
|
withdrawalChargeAmountYTD
number
required
|
This is the total value of withdrawal charges reported to HMRC for the current tax year to date. |
|
fundsDeductedDuringWithdrawal
boolean
required
|
This confirms if the investor was charged and funds were deducted at the time of the withdrawal. |
|
withdrawalReason
string
required
|
This is used by HMRC to decide how the withdrawal charge is processed. Limited to the following possible values: Regular withdrawal
Superseded withdrawal
|
|
supersededBy
string
optional
|
The ID of the transaction that supersedes the current one.
Must conform to the regular expression
For example: |
|
supersede
object
optional
|
Correct an existing withdrawal charge. You can request an additional charge, reduce a charge, or refund a charge. |
|
originalTransactionId
string
required
|
The transactionId of the original withdrawal charge affected by the correction or recovery. This is used together with the originalWithdrawalChargeAmount to make sure the right charge is replaced.
Must conform to the regular expression
For example: |
|
originalWithdrawalChargeAmount
number
required
|
This is how much was in the withdrawalChargeAmount in the original request. |
|
transactionResult
number
required
|
The amount to be added to or recovered from the original withdrawal charge. |
|
reason
string
required
|
Confirm whether an additional charge is due or whether the investor is owed some money. Limited to the following possible values: Additional withdrawal
Withdrawal reduction
Withdrawal refund
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The transactionId does not match HMRC’s records |
404 (Not Found) |
WITHDRAWAL_CHARGE_TRANSACTION_NOT_FOUND |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Response |
|---|---|
|
Withdrawal transaction which has been superseded
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"automaticRecoveryAmount": 250,
"withdrawalAmount": 1000,
"withdrawalChargeAmount": 250,
"withdrawalChargeAmountYTD": 500,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal",
"supersededBy": "2345678903"
}
|
|
Withdrawal transaction which has not been superseded
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"automaticRecoveryAmount": 250,
"withdrawalAmount": 1000,
"withdrawalChargeAmount": 250,
"withdrawalChargeAmountYTD": 500,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Regular withdrawal"
}
|
|
Withdrawal transaction which supersedes another
lisaManagerReferenceNumber: |
{
"claimPeriodStartDate": "2017-12-06",
"claimPeriodEndDate": "2018-01-05",
"automaticRecoveryAmount": 250,
"withdrawalAmount": 2000,
"withdrawalChargeAmount": 500,
"withdrawalChargeAmountYTD": 750,
"fundsDeductedDuringWithdrawal": true,
"withdrawalReason": "Superseded withdrawal",
"supersede": {
"originalTransactionId": "2345678901",
"originalWithdrawalChargeAmount": 250,
"transactionResult": 250,
"reason": "Additional withdrawal"
}
}
|
|
Invalid LISA Manager Reference Number
lisaManagerReferenceNumber: |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Invalid Account ID
lisaManagerReferenceNumber: |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Account ID does not exist
lisaManagerReferenceNumber: |
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "accountId does not match HMRC’s records"
}
|
|
Transaction ID does not exist
lisaManagerReferenceNumber: |
HTTP status:
{
"code": "WITHDRAWAL_CHARGE_TRANSACTION_NOT_FOUND",
"message": "transactionId does not match HMRC’s records"
}
|
Bonus requests
Bonus requests resources
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions
Request a bonus payment from HMRC and provide a reason for the request. You can also correct a bonus claim during or after the claim reporting period. You can repay any overpaid amounts to HMRC and receive additional payments from corrected claims.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 4000.00,
"totalSubsYTD": 4000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 1000.00,
"totalBonusDueYTD": 1000.00,
"claimReason": "Superseded Bonus"
},
"supersede": {
"automaticRecoveryAmount": 1000.00,
"originalTransactionId": "0000456789",
"originalBonusDueForPeriod": 1000.00,
"transactionResult": -1000.00,
"reason": "Bonus recovery"
}
}
| Name | Description |
|---|---|
|
lifeEventId
string
optional
|
The reference number you get when you report a life event.
Must conform to the regular expression
For example: |
|
periodStartDate
string
required
|
The first date in the claim period. The periodStartDate must be the 6th day of the month. You cannot enter a date in the future for periodStartDate. Date in the format
For example: |
|
periodEndDate
string
required
|
The end date of the claim period. The periodEndDate must be the 5th day of the month. It has to be the month after the periodStartDate. Date in the format
For example: |
|
htbTransfer
object
optional
|
Details about Help to Buy funds. |
|
htbTransferInForPeriod
number
required
|
The total amount of Help to Buy funds in the account during the claim period. You can include an amount up to 2 decimal places. |
|
htbTransferTotalYTD
number
required
|
The total amount of Help to Buy funds in the account in the tax year to date. You can include an amount up to 2 decimal places. If there is a number in htbTransferInForPeriod, then the number in htbTransferTotalYTD must be greater than 0. |
|
inboundPayments
object
required
|
Details about qualifying deposits and account balance. |
|
newSubsForPeriod
number
optional
|
The total value of new qualifying deposits paid in to the account during the claim period. You can include an amount up to 2 decimal places. |
|
newSubsYTD
number
required
|
The total value of new qualifying deposits paid in to the account during the tax year to date. You can include an amount up to 2 decimal places. If there is a number in newSubsForPeriod, then the number in newSubsYTD must be greater than 0. |
|
totalSubsForPeriod
number
required
|
The total amount in the account during the claim period that qualifies for a bonus payment. You can include an amount up to 2 decimal places. The totalSubsForPeriod must always be greater than 0 except when bonusDueForPeriod is 0. |
|
totalSubsYTD
number
required
|
The total amount in the account during the tax year to date that qualifies for a bonus payment. You can include an amount up to 2 decimal places. The totalSubsYTD must be the same as or more than totalSubsForPeriod. |
|
bonuses
object
required
|
Bonus payment details. |
|
bonusDueForPeriod
number
required
|
The total bonus payment amount due for the claim period. You can include an amount up to 2 decimal places. If you supersede this claim and the supersededReason is ‘bonus recovery’, then the bonusDueForPeriod can be 0. If not, it must always be greater than 0. |
|
totalBonusDueYTD
number
required
|
The total bonus payment amount due for the tax year to date. You can include an amount up to 2 decimal places. This cannot be less than bonusDueForPeriod. |
|
bonusPaidYTD
number
optional
|
The total bonus payment that has already been claimed and paid in the tax year to date. You can include an amount up to 2 decimal places. |
|
claimReason
string
required
|
The reason the bonus payment was claimed. Limited to the following possible values: Life Event
Regular Bonus
Superseded Bonus
|
|
supersede
object
optional
|
Correct an existing bonus claim with an additional bonus or a recovery of an overpaid amount. |
|
automaticRecoveryAmount
number
optional
|
This is the amount HMRC can collect from the LISA manager in bonus recovery cases. If there are no funds available, this value must be 0. |
|
originalTransactionId
string
required
|
The transactionId of the original bonus affected by the correction or recovery. This is used together with the originalBonusDueForPeriod to make sure the right bonus transaction is replaced.
Must conform to the regular expression
For example: |
|
originalBonusDueForPeriod
number
required
|
This is how much was in the bonusDueForPeriod in the original bonus request. |
|
transactionResult
number
required
|
The amount to be added to or recovered from the original bonus. |
|
reason
string
required
|
Confirm whether an additional bonus amount is due or funds need to be recovered. Limited to the following possible values: Bonus recovery
Additional bonus
|
Response
HTTP status: 201 (Created)
{
"data": {
"transactionId": "0123456789",
"message": "Bonus transaction created"
},
"success": true,
"status": 201
}
{
"data": {
"transactionId": "0023456789",
"message": "Bonus transaction created - late notification"
},
"success": true,
"status": 201
}
{
"data": {
"transactionId": "0000456789",
"message": "Bonus transaction superseded"
},
"success": true,
"status": 201
}
| Name | Description |
|---|---|
|
data
object
required
|
Response details. |
|
transactionId
string
required
|
The transaction’s ID reference number. You must store this ID as it is needed for other API calls.
Must conform to the regular expression |
|
message
string
required
|
A human-readable explanation for the result of the API call. Limited to the following possible values: Bonus transaction created
Bonus transaction created - late notification
Bonus transaction superseded
|
|
success
boolean
required
|
Whether the API call was successful or not. Always true. |
|
status
number
required
|
The HTTP status of the result of the API call. Always 201. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
There is a problem with the request data |
403 (Forbidden) |
FORBIDDEN |
|
lifeEventId is required when the claimReason is a life event |
403 (Forbidden) |
LIFE_EVENT_NOT_PROVIDED |
|
The bonus amount given is above the maximum annual amount, or the qualifying deposits are above the maximum annual amount or the bonus claim does not equal the correct percentage of qualifying funds |
403 (Forbidden) |
BONUS_CLAIM_ERROR |
|
The LISA account is already closed |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CLOSED |
|
The LISA account is already cancelled |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_CANCELLED |
|
The LISA account is already void |
403 (Forbidden) |
INVESTOR_ACCOUNT_ALREADY_VOID |
|
Help to buy is only applicable for claims within the 2017-18 tax year |
403 (Forbidden) |
HELP_TO_BUY_NOT_APPLICABLE |
|
The timescale for claiming a bonus has passed. The claim period lasts for 6 years and 14 days |
403 (Forbidden) |
BONUS_CLAIM_TIMESCALES_EXCEEDED |
|
originalTransactionId and the originalBonusDueForPeriod amount do not match the information in the original bonus request |
403 (Forbidden) |
SUPERSEDED_BONUS_CLAIM_AMOUNT_MISMATCH |
|
The calculation from your superseded bonus claim is incorrect |
403 (Forbidden) |
SUPERSEDED_BONUS_REQUEST_OUTCOME_ERROR |
|
This account is not eligible for a bonus payment because the investor already has another LISA account |
403 (Forbidden) |
ACCOUNT_ERROR_NO_SUBSCRIPTIONS_THIS_TAX_YEAR |
|
The lifeEventId does not match with HMRC’s records |
404 (Not Found) |
LIFE_EVENT_NOT_FOUND |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
|
The investor’s bonus payment has already been requested. |
409 (Conflict) |
BONUS_CLAIM_ALREADY_EXISTS |
|
This bonus claim has already been superseded |
409 (Conflict) |
BONUS_CLAIM_ALREADY_SUPERSEDED |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Request Payload | Response |
|---|---|---|
|
Request with a valid payload, LISA Manager reference number and account ID
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Bonus transaction created",
"transactionId": "0123456789"
}
}
|
|
Request with a valid payload, LISA Manager reference number and account ID (late notification)
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567800",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Bonus transaction created - late notification",
"transactionId": "0023456789"
}
}
|
|
Request with a valid payload, LISA Manager reference number and account ID (regular bonus)
lisaManagerReferenceNumber: |
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Regular Bonus"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Bonus transaction created",
"transactionId": "0003456789"
}
}
|
|
Superseded transaction - Bonus recovery
lisaManagerReferenceNumber: |
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 4000.00,
"totalSubsYTD": 4000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 1000.00,
"totalBonusDueYTD": 1000.00,
"claimReason": "Superseded Bonus"
},
"supersede": {
"automaticRecoveryAmount": 1000.00,
"originalTransactionId": "0123456789",
"originalBonusDueForPeriod": 1000.00,
"transactionResult": -1000.00,
"reason": "Bonus recovery"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Bonus transaction superseded",
"transactionId": "0000456789"
}
}
|
|
Superseded transaction - Additional bonus
lisaManagerReferenceNumber: |
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 4000.00,
"totalSubsYTD": 4000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 1000.00,
"totalBonusDueYTD": 1000.00,
"claimReason": "Superseded Bonus"
},
"supersede": {
"originalTransactionId": "0003456789",
"originalBonusDueForPeriod": 4000.00,
"transactionResult": 4000.00,
"reason": "Additional bonus"
}
}
|
HTTP status:
{
"status": 201,
"success": true,
"data": {
"message": "Bonus transaction superseded",
"transactionId": "0000056789"
}
}
|
|
Request with a valid payload and account ID, but an invalid LISA Manager reference number
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Request with a valid payload and LISA Manager reference number, but an invalid account ID
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Request containing invalid and/or missing data
lisaManagerReferenceNumber: |
{
"lifeEventId": true,
"periodStartDate": "2017-04-06",
"periodEndDate": "05-05-2017",
"htbTransfer": {
"htbTransferInForPeriod": 5.50,
"htbTransferTotalYTD": 5.5001
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"claimReason": "X"
},
"supersede": {
"originalTransactionId": "ABC123",
"originalBonusDueForPeriod": true,
"transactionResult": -10.005,
"reason": "Recovery"
}
}
|
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Bad Request",
"errors": [
{
"code": "INVALID_DATA_TYPE",
"message": "Invalid data type has been used",
"path": "/lifeEventId"
},
{
"code": "INVALID_DATE",
"message": "Date is invalid",
"path": "/periodEndDate"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "Amount cannot be negative, and can only have up to 2 decimal places",
"path": "/htbTransfer/htbTransferTotalYTD"
},
{
"code": "MISSING_FIELD",
"message": "This field is required",
"path": "/bonuses/totalBonusDueYTD"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/bonuses/claimReason"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/supersede/originalTransactionId"
},
{
"code": "INVALID_DATA_TYPE",
"message": "Invalid data type has been used",
"path": "/supersede/originalBonusDueForPeriod"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "Amount can only have up to 2 decimal places",
"path": "/supersede/transactionResult"
},
{
"code": "INVALID_FORMAT",
"message": "Invalid format has been used",
"path": "/supersede/reason"
}
]
}
|
|
Request with invalid monetary amounts and/or invalid dates
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567891",
"periodStartDate": "9999-04-05",
"periodEndDate": "2016-06-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 0.00,
"newSubsYTD": 0.00,
"totalSubsForPeriod": 0.0,
"totalSubsYTD": 0.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 0.0,
"totalBonusDueYTD": 0.0,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "FORBIDDEN",
"message": "There is a problem with the request data",
"errors": [
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "newSubsForPeriod and htbTransferInForPeriod cannot both be 0",
"path": "/inboundPayments/newSubsForPeriod"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "newSubsForPeriod and htbTransferInForPeriod cannot both be 0",
"path": "/htbTransfer/htbTransferInForPeriod"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "totalSubsForPeriod must be more than 0",
"path": "/inboundPayments/totalSubsForPeriod"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "bonusDueForPeriod must be more than 0",
"path": "/bonuses/bonusDueForPeriod"
},
{
"code": "INVALID_MONETARY_AMOUNT",
"message": "totalBonusDueYTD must be more than 0",
"path": "/bonuses/totalBonusDueYTD"
},
{
"code": "INVALID_DATE",
"message": "The periodStartDate must be the 6th day of the month",
"path": "/periodStartDate"
},
{
"code": "INVALID_DATE",
"message": "The periodEndDate must be the 5th day of the month which occurs after the periodStartDate",
"path": "/periodEndDate"
},
{
"code": "INVALID_DATE",
"message": "The periodStartDate may not be a future date",
"path": "/periodStartDate"
},
{
"code": "INVALID_DATE",
"message": "The periodEndDate cannot be before 6 April 2017",
"path": "/periodEndDate"
}
]
}
|
|
Request with a 'claimReason' of 'Life Event', but without a lifeEventId
lisaManagerReferenceNumber: |
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "LIFE_EVENT_NOT_PROVIDED",
"message": "lifeEventId is required when the claimReason is a life event"
}
|
|
Request containing invalid bonus payment figures
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567801",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "BONUS_CLAIM_ERROR",
"message": "The bonus amount given is above the maximum annual amount, or the qualifying deposits are above the maximum annual amount or the bonus claim does not equal the correct percentage of qualifying funds"
}
|
|
Request for an account that has already been closed
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567802",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CLOSED",
"message": "The LISA account is already closed"
}
|
|
Request for an account that has already been voided
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567802",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_VOID",
"message": "The LISA account is already void"
}
|
|
Request for an account that has already been cancelled
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567802",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED",
"message": "The LISA account is already cancelled"
}
|
|
Request for a bonus claim after 5 April 2018 containing help to buy funds.
lisaManagerReferenceNumber: |
{
"periodStartDate": "2018-04-06",
"periodEndDate": "2018-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 1000.00,
"htbTransferTotalYTD": 1000.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10500.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Regular Bonus"
}
}
|
HTTP status:
{
"code": "HELP_TO_BUY_NOT_APPLICABLE",
"message": "Help to buy is only applicable for claims within the 2017-18 tax year"
}
|
|
Superseded transaction containing details which don't match an existing transaction
lisaManagerReferenceNumber: |
{
"periodStartDate": "2018-04-06",
"periodEndDate": "2018-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10500.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Superseded Bonus"
},
"supersede": {
"automaticRecoveryAmount": 1000.00,
"originalTransactionId": "1234567892",
"originalBonusDueForPeriod": 2000.00,
"transactionResult": -1000.00,
"reason": "Bonus recovery"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_BONUS_CLAIM_AMOUNT_MISMATCH",
"message": "originalTransactionId and the originalBonusDueForPeriod amount do not match the information in the original bonus request"
}
|
|
Superseded transaction with an outcome error
lisaManagerReferenceNumber: |
{
"periodStartDate": "2018-04-06",
"periodEndDate": "2018-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10500.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Superseded Bonus"
},
"supersede": {
"automaticRecoveryAmount": 1000.00,
"originalTransactionId": "1234567892",
"originalBonusDueForPeriod": 2000.00,
"transactionResult": -1000.00,
"reason": "Bonus recovery"
}
}
|
HTTP status:
{
"code": "SUPERSEDED_BONUS_REQUEST_OUTCOME_ERROR",
"message": "The calculation from your superseded bonus claim is incorrect"
}
|
|
This account is not eligible for a bonus payment because the investor already has another LISA account
lisaManagerReferenceNumber: |
{
"periodStartDate": "2018-04-06",
"periodEndDate": "2018-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10500.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Superseded Bonus"
},
"supersede": {
"automaticRecoveryAmount": 1000.00,
"originalTransactionId": "1234567892",
"originalBonusDueForPeriod": 2000.00,
"transactionResult": -1000.00,
"reason": "Bonus recovery"
}
}
|
HTTP status:
{
"code": "ACCOUNT_ERROR_NO_SUBSCRIPTIONS_THIS_TAX_YEAR",
"message": "This account is not eligible for a bonus payment because the investor already has another LISA account"
}
|
|
Request containing a life event ID that does not exist
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567803",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "LIFE_EVENT_NOT_FOUND",
"message": "The lifeEventId does not match with HMRC’s records"
}
|
|
Request containing an account ID that does not exist
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567804",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
|
Request for a bonus claim that has already been requested
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "BONUS_CLAIM_ALREADY_EXISTS",
"message": "The investor’s bonus payment has already been requested",
"transactionId": "0123456789"
}
|
|
Request to supersede a transaction that has already been superseded
lisaManagerReferenceNumber: |
{
"periodStartDate": "2018-04-06",
"periodEndDate": "2018-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10500.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Superseded Bonus"
},
"supersede": {
"automaticRecoveryAmount": 1000.00,
"originalTransactionId": "0000006789",
"originalBonusDueForPeriod": 2000.00,
"transactionResult": -1000.00,
"reason": "Bonus recovery"
}
}
|
HTTP status:
{
"code": "BONUS_CLAIM_ALREADY_SUPERSEDED",
"message": "This bonus claim has already been superseded",
"transactionId": "0000456789"
}
|
|
Request with an invalid 'Accept' header
lisaManagerReferenceNumber: |
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0.00,
"htbTransferTotalYTD": 0.00
},
"inboundPayments": {
"newSubsForPeriod": 4000.00,
"newSubsYTD": 4000.00,
"totalSubsForPeriod": 40000.00,
"totalSubsYTD": 40000.00
},
"bonuses": {
"bonusPaidYTD": 0.0,
"bonusDueForPeriod": 10000.00,
"totalBonusDueYTD": 10000.00,
"claimReason": "Life Event"
}
}
|
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions/{transactionId}
Use an investor’s transaction ID to get a request for a bonus payment that has been submitted to HMRC.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
|
transactionId
string
required
|
The ID for the transaction.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0,
"htbTransferTotalYTD": 0
},
"inboundPayments": {
"newSubsForPeriod": 4000,
"newSubsYTD": 4000,
"totalSubsForPeriod": 4000,
"totalSubsYTD": 4000
},
"bonuses": {
"bonusDueForPeriod": 1000,
"totalBonusDueYTD": 1000,
"claimReason": "Life Event"
}
}
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000,
"newSubsYTD": 4000,
"totalSubsForPeriod": 40000,
"totalSubsYTD": 40000
},
"bonuses": {
"bonusPaidYTD": 0,
"bonusDueForPeriod": 10000,
"totalBonusDueYTD": 10000,
"claimReason": "Regular Bonus"
}
}
{
"periodStartDate": "2018-04-06",
"periodEndDate": "2018-05-05",
"inboundPayments": {
"newSubsForPeriod": 0,
"newSubsYTD": 0,
"totalSubsForPeriod": 0,
"totalSubsYTD": 0
},
"bonuses": {
"bonusDueForPeriod": 0,
"totalBonusDueYTD": 0,
"claimReason": "Superseded Bonus"
},
"supersede" : {
"automaticRecoveryAmount": 300,
"originalTransactionId": "0000456789",
"originalBonusDueForPeriod": -300,
"transactionResult": 300,
"reason": "Bonus recovery"
}
}
| Name | Description |
|---|---|
|
lifeEventId
string
optional
|
A reference number for a life event.
Must conform to the regular expression
For example: |
|
periodStartDate
string
required
|
The first date in the claim period. Date in the format
For example: |
|
periodEndDate
string
required
|
The end date of the claim period. Date in the format
For example: |
|
htbTransfer
object
optional
|
Details about Help to Buy funds. |
|
htbTransferInForPeriod
number
required
|
The total amount of Help to Buy funds in the account during the claim period. |
|
htbTransferTotalYTD
number
required
|
The total amount of Help to Buy funds in the account in the tax year to date. |
|
inboundPayments
object
required
|
Details about qualifying deposits and account balance. |
|
newSubsForPeriod
number
optional
|
The total value of new qualifying deposits paid in to the account during the claim period. |
|
newSubsYTD
number
required
|
The total value of new qualifying deposits paid in to the account during the tax year to date. |
|
totalSubsForPeriod
number
required
|
The total amount in the account during the claim period that qualifies for a bonus payment. |
|
totalSubsYTD
number
required
|
The total amount in the account during the tax year to date that qualifies for a bonus payment. |
|
bonuses
object
required
|
Bonus payment details. |
|
bonusDueForPeriod
number
required
|
The total bonus payment amount due for the claim period. |
|
totalBonusDueYTD
number
required
|
The total bonus payment amount due for the tax year to date. |
|
bonusPaidYTD
number
optional
|
The total bonus payment that has already been claimed and paid in the tax year to date. |
|
claimReason
string
required
|
The reason the bonus payment was claimed. Limited to the following possible values: Life Event
Regular Bonus
Superseded Bonus
|
|
supersededBy
string
optional
|
The ID of the transaction that supersedes the current one.
Must conform to the regular expression
For example: |
|
supersede
object
optional
|
Correct an existing bonus claim with an additional bonus or a recovery of an overpaid amount. |
|
automaticRecoveryAmount
number
optional
|
This is the amount HMRC can collect from the LISA manager in bonus recovery cases. If there are no funds available, this value must be 0. |
|
originalTransactionId
string
required
|
The transactionId of the original bonus affected by the correction or recovery. This is used together with the originalBonusDueForPeriod to make sure the right bonus transaction is replaced.
Must conform to the regular expression
For example: |
|
originalBonusDueForPeriod
number
required
|
This is how much was in the bonusDueForPeriod in the original bonus request. |
|
transactionResult
number
required
|
The amount to be added to or recovered from the original bonus. |
|
reason
string
required
|
Confirm whether an additional bonus amount is due or funds need to be recovered. Limited to the following possible values: Bonus recovery
Additional bonus
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The transactionId does not match HMRC’s records |
404 (Not Found) |
BONUS_PAYMENT_TRANSACTION_NOT_FOUND |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Response |
|---|---|
|
Retrieve details for a bonus payment associated with a LISA account
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"lifeEventId": "1234567891",
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"htbTransfer": {
"htbTransferInForPeriod": 0,
"htbTransferTotalYTD": 0
},
"inboundPayments": {
"newSubsForPeriod": 4000,
"newSubsYTD": 4000,
"totalSubsForPeriod": 40000,
"totalSubsYTD": 40000
},
"bonuses": {
"bonusPaidYTD": 0,
"bonusDueForPeriod": 10000,
"totalBonusDueYTD": 10000,
"claimReason": "Life Event"
},
"supersededBy": "0000456789"
}
|
|
Retrieve details for a bonus payment associated with a LISA account (regular bonus)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000,
"newSubsYTD": 4000,
"totalSubsForPeriod": 40000,
"totalSubsYTD": 40000
},
"bonuses": {
"bonusPaidYTD": 0,
"bonusDueForPeriod": 10000,
"totalBonusDueYTD": 10000,
"claimReason": "Regular Bonus"
},
"supersededBy": "0000056789"
}
|
|
Retrieve a superseded transaction (bonus recovery)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000,
"newSubsYTD": 4000,
"totalSubsForPeriod": 4000,
"totalSubsYTD": 4000
},
"bonuses": {
"bonusPaidYTD": 0,
"bonusDueForPeriod": 1000,
"totalBonusDueYTD": 1000,
"claimReason": "Superseded Bonus"
},
"supersede": {
"automaticRecoveryAmount": 1000,
"originalTransactionId": "0123456789",
"originalBonusDueForPeriod": 1000,
"transactionResult": -1000,
"reason": "Bonus recovery"
}
}
|
|
Retrieve a superseded transaction (additional bonus)
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"periodStartDate": "2017-04-06",
"periodEndDate": "2017-05-05",
"inboundPayments": {
"newSubsForPeriod": 4000,
"newSubsYTD": 4000,
"totalSubsForPeriod": 4000,
"totalSubsYTD": 4000
},
"bonuses": {
"bonusPaidYTD": 0,
"bonusDueForPeriod": 1000,
"totalBonusDueYTD": 1000,
"claimReason": "Superseded Bonus"
},
"supersede": {
"originalTransactionId": "0003456789",
"originalBonusDueForPeriod": 4000,
"transactionResult": 4000,
"reason": "Additional bonus"
}
}
|
|
Request with an invalid LISA Manager reference number
lisaManagerReferenceNumber: 123456 |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Request with an invalid accountId
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
|
Request with an invalid bonus payment transaction
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BONUS_PAYMENT_TRANSACTION_NOT_FOUND",
"message": "transactionId does not match HMRC’s records"
}
|
|
Request with an invalid LISA account
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
Payments and debts
Payments and debts resources
/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions/{transactionId}/payments
Use an investor’s transaction ID to get payment details for a bonus claim or withdrawal charge, including when the amount is due to be paid or collected.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
accountId
string
required
|
The ID for the account. This will be generated by the LISA Manager and will only be unique when used in combination with lisaManagerReferenceNumber. Any special characters should be URL encoded.
Must conform to the regular expression
For example: |
|
transactionId
string
required
|
The ID for the transaction.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"transactionId": "0123456789",
"transactionType": "Payment",
"paymentStatus": "Paid",
"paymentDate": "2017-05-20",
"paymentReference": "002630000993",
"paymentAmount": 1000
}
{
"transactionId": "0000000200",
"paymentStatus": "Pending"
}
| Name | Description |
|---|---|
|
transactionId
string
required
|
The transactionId for which the payment details have been requested.
Must conform to the regular expression |
|
transactionType
string
optional
|
The type of transaction. This can be money owed to HMRC (Debt), or money paid out by HMRC (Payment). Limited to the following possible values: Payment
Debt
|
|
paymentDate
string
optional
|
The date payment was made. Date in the format
For example: |
|
paymentDueDate
string
optional
|
The date the payment is due. Date in the format
For example: |
|
paymentStatus
string
required
|
The status of the transaction being requested. Limited to the following possible values: Paid
Pending
Due
Collected
Cancelled
Void
Superseded
Charge refund cancelled
|
|
paymentReference
string
optional
|
The reference of the payment made.
Must conform to the regular expression
For example: |
|
paymentAmount
number
optional
|
The amount paid for the transaction.
For example: |
|
supersededBy
string
optional
|
The ID of the transaction that supersedes the current one.
Must conform to the regular expression |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter accountId in the correct format, like ABC12345 |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
The transactionId does not match HMRC’s records |
404 (Not Found) |
TRANSACTION_NOT_FOUND |
|
Enter a real accountId |
404 (Not Found) |
INVESTOR_ACCOUNTID_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Response |
|---|---|
Request for a paid payment lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "0123456789",
"transactionType": "Payment",
"paymentStatus": "Paid",
"paymentDate": "2017-06-20",
"paymentAmount": 1000,
"paymentReference": "002630000993"
}
|
Request for a pending transaction (payment or debt) lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "0000000200",
"paymentStatus": "Pending"
}
|
Request for a pending payment with a due date lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "3000000200",
"transactionType": "Payment",
"paymentStatus": "Pending",
"paymentDueDate": "2017-06-20"
}
|
Request for a cancelled transaction lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "1000000200",
"paymentStatus": "Cancelled",
}
|
Request for a void transaction lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "2000000200",
"paymentStatus": "Void"
}
|
Request for a debt which is due to be collected lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "2345678902",
"transactionType": "Debt",
"paymentStatus": "Due",
"paymentDueDate": "2018-01-20",
"paymentAmount": 200,
"paymentReference": "0000002630000993"
}
|
Request for a debt which has been collected lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "2345678903",
"transactionType": "Debt",
"paymentStatus": "Collected",
"paymentDate": "2018-02-20",
"paymentAmount": 250,
"paymentReference": "0000002630000994"
}
|
Request for a transaction which was superseded before being paid lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "2345678901",
"paymentStatus": "Superseded",
"supersededBy": "2345678903"
}
|
Request to refund withdrawal charge has been cancelled lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"transactionId": "0000000403",
"transactionType": "Payment",
"paymentStatus": "Charge refund cancelled"
}
|
Request with a valid account ID and Transaction ID, but an invalid LISA Manager reference number lisaManagerReferenceNumber: 123456 |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
Request with a valid LISA Manager reference number and Transaction ID, but an invalid account ID lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter accountId in the correct format, like ABC12345"
}
|
Request for a transaction that does not exist lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "TRANSACTION_NOT_FOUND",
"message": "transactionId does not match HMRC’s records"
}
|
Request for an account that does not exist lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "INVESTOR_ACCOUNTID_NOT_FOUND",
"message": "Enter a real accountId"
}
|
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|
/lifetime-isa/manager/{lisaManagerReferenceNumber}/payments
Get a list of all pending and paid payments from HMRC and due and collected debts owed to HMRC in a specific date range.
Authorisation
This endpoint is
user-restricted
and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:lisa scope.
Path parameters
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
Query parameters
| Name | Description |
|---|---|
|
startDate
string
required
|
The first date in the claim period you want to search. This must be the 6th day of the month. This cannot be before 6 April 2017.
Must conform to the regular expression
For example: |
|
endDate
string
required
|
The last date of the claim period you want to search. This must be the 5th day of the month. This cannot be in the future, before the startDate, or more than a year after the startDate. It must be at least one month after the startDate.
Must conform to the regular expression
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.2.0+json
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:lisa scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"lisaManagerReferenceNumber": "Z123456",
"payments": [
{
"transactionType": "Payment",
"status": "Paid",
"paymentAmount": 10000,
"paymentDate": "2017-06-01",
"paymentReference": "1040000872"
},
{
"transactionType": "Payment",
"status": "Pending",
"paymentAmount": 12000,
"dueDate": "2017-07-04"
},
{
"transactionType": "Debt",
"status": "Collected",
"paymentAmount": 1000,
"paymentDate": "2017-08-04",
"paymentReference": "1040000985"
},
{
"transactionType": "Debt",
"status": "Due",
"paymentAmount": 1100,
"dueDate": "2017-09-04"
}
]
}
| Name | Description |
|---|---|
|
lisaManagerReferenceNumber
string
required
|
The reference given to the LISA provider when they applied for approval from HMRC.
Must conform to the regular expression
For example: |
|
payments
array
required
|
Pending and paid payments from HMRC and due and collected debts owed to HMRC. |
|
transactionType
string
required
|
The type of transaction. This can be money owed to HMRC (Debt), or money paid out by HMRC (Payment). Limited to the following possible values: Debt
Payment
|
|
status
string
required
|
The status of the transaction being requested. Limited to the following possible values: Pending
Paid
Due
Collected
|
|
paymentAmount
number
required
|
Amount pending or paid to the LISA provider, or the amount due or collected from the LISA provider.
For example: |
|
paymentReference
string
optional
|
Payment reference number. This will only be returned for paid payments and collected debts.
Must conform to the regular expression
For example: |
|
paymentDate
string
optional
|
The date the payment was paid or the debt was collected. This will only be returned for paid payments and collected debts. Date in the format
For example: |
|
dueDate
string
optional
|
The date the payment or debt is due to be paid or collected. This will only be returned for pending payments and due debts. Date in the format
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
Bad Request |
400 (Bad Request) |
BAD_REQUEST |
|
Enter lisaManagerReferenceNumber in the correct format, like Z1234 |
400 (Bad Request) |
BAD_REQUEST |
|
startDate is in the wrong format |
400 (Bad Request) |
BAD_REQUEST |
|
endDate is in the wrong format |
400 (Bad Request) |
BAD_REQUEST |
|
startDate and endDate are in the wrong format |
400 (Bad Request) |
BAD_REQUEST |
|
Enter a real lisaManagerReferenceNumber |
401 (Unauthorized) |
UNAUTHORIZED |
|
endDate cannot be in the future |
403 (Forbidden) |
FORBIDDEN |
|
endDate cannot be before startDate |
403 (Forbidden) |
FORBIDDEN |
|
startDate cannot be before 6 April 2017 |
403 (Forbidden) |
FORBIDDEN |
|
endDate cannot be more than a year after startDate |
403 (Forbidden) |
FORBIDDEN |
|
No payments or debts exist for this date range |
404 (Not Found) |
TRANSACTION_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
| Scenario | Response |
|---|---|
|
Request for payments where some are found
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"lisaManagerReferenceNumber": "Z123456",
"payments": [
{
"transactionType": "Payment",
"status": "Paid",
"paymentAmount": 10000,
"paymentDate": "2017-06-01",
"paymentReference": "1040000872"
},
{
"transactionType": "Payment",
"status": "Pending",
"paymentAmount": 12000,
"dueDate": "2017-07-04"
},
{
"transactionType": "Debt",
"status": "Collected",
"paymentAmount": 1000,
"paymentDate": "2017-08-04",
"paymentReference": "1040000985"
},
{
"transactionType": "Debt",
"status": "Due",
"paymentAmount": 1100,
"dueDate": "2017-09-04"
}
]
}
|
|
Request for payments where none are found
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "TRANSACTION_NOT_FOUND",
"message": "No payments or debts exist for this date range"
}
|
|
Request with an invalid LISA Manager reference number
lisaManagerReferenceNumber: 123456 |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234"
}
|
|
Request with startDate in the wrong format
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "startDate is in the wrong format"
}
|
|
Request with endDate in the wrong format
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "endDate is in the wrong format"
}
|
|
Request with startDate and endDate in the wrong format
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "BAD_REQUEST",
"message": "startDate and endDate are in the wrong format"
}
|
|
Request with and endDate in the future
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "FORBIDDEN",
"message": "endDate cannot be in the future"
}
|
|
Request with an endDate before the startDate
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "FORBIDDEN",
"message": "endDate cannot be before startDate"
}
|
|
startDate cannot be before 6 April 2017
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "FORBIDDEN",
"message": "startDate cannot be before 6 April 2017"
}
|
|
Request with an endDate over a year after startDate
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "FORBIDDEN",
"message": "endDate cannot be more than a year after startDate"
}
|
|
Request with an invalid 'Accept' header
lisaManagerReferenceNumber: Use your test user profile |
HTTP status:
{
"code": "ACCEPT_HEADER_INVALID",
"message": "The accept header is missing or invalid"
}
|