• Register
• Sign in

 

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.

Skip to main content

Endpoints

/lifetime-isa/manager/{lisaManagerReferenceNumber}

Get a list of all available endpoints

GET

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234

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.

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
_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: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/investors

Create a LISA investor

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234

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.

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 ^((?!(BG|GB|KN|NK|NT|TN|ZZ)|(D|F|I|Q|U|V)[A-Z]|[A-Z](D|F|I|O|Q|U|V))[A-Z]{2})[0-9]{6}[A-D]?$ For example: BC123456D
firstName string required	The investor’s first name. Must conform to the regular expression ^[a-zA-Z &`\-\'^]{1,35}$ For example: FirstName
lastName string required	The investor’s last name. Must conform to the regular expression ^[a-zA-Z &`\-\'^]{1,35}$ For example: LastName
dateOfBirth string required	The investor’s date of birth. This cannot be in the future. Date in the format YYYY-MM-DD For example: 1989-04-22

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 ^\d{10}$
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: 201 (Created) { "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: 400 (Bad Request) { "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: 400 (Bad Request) { "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: 403 (Forbidden) { "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 Accept: application/vnd.hmrc.1.0	{ "investorNINO": "AA123456A", "firstName": "First Name", "lastName": "Last Name", "dateOfBirth": "1985-03-25" }	HTTP status: 406 (Not Acceptable) { "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: 409 (Conflict) { "code": "INVESTOR_ALREADY_EXISTS", "message": "The investor already has a record with HMRC", "id": "1234567890" }

Close section

LISA accounts

LISA accounts resources

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts

Create or transfer a LISA account

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234

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.

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 ^\d{10}$ For example: 1234567890
accountId string required	The provider’s own unique reference number for the investor’s LISA account. Must conform to the regular expression ^[a-zA-Z0-9 :/-]{1,20}$ For example: AB9876543210
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 YYYY-MM-DD For example: 2017-04-20
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: AB9876543210
transferredFromLMRN string required	The reference given to the LISA provider when they applied for approval from HMRC. Must conform to the regular expression ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 YYYY-MM-DD For example: 2017-04-20

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 ^[a-zA-Z0-9 :/-]{1,20}$
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: 201 (Created) { "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: 201 (Created) { "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: 201 (Created) { "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: 201 (Created) { "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: 400 (Bad Request) { "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: 400 (Bad Request) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_VOID", "message": "The LISA account is already void" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile Accept: application/vnd.hmrc.1.0	{ "investorId": "9876543210", "creationReason": "New", "accountId": "1234567890", "firstSubscriptionDate": "2017-04-06" }	HTTP status: 406 (Not Acceptable) { "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: 409 (Conflict) { "code": "INVESTOR_ACCOUNT_ALREADY_EXISTS", "message": "This investor already has a LISA account", "accountId": "1234567890" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/reinstate-account

Reinstate a LISA account

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234

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.

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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: AB9876543210

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 ^[a-zA-Z0-9 :/-]{1,20}$
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: 200 (OK) { "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: 400 (Bad Request) { "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: 400 (Bad Request) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 403 (Forbidden) { "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: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}

Get account details

GET

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 ^\d{10}$ For example: 1234567890
accountId string required	The provider’s own unique reference number for the investor’s LISA account. Must conform to the regular expression ^[a-zA-Z0-9 :/-]{1,20}$ For example: AB9876543210
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 YYYY-MM-DD For example: 2017-04-20
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 YYYY-MM-DD For example: 2017-04-20
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: AB9876543210
transferredFromLMRN string required	The reference given to the LISA provider when they applied for approval from HMRC. Must conform to the regular expression ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 YYYY-MM-DD For example: 2017-04-20

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 accountId: 1234567890	HTTP status: 200 (OK) { "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 accountId: 1234567891	HTTP status: 200 (OK) { "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 accountId: 1234567892	HTTP status: 200 (OK) { "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 accountId: 1234567893	HTTP status: 200 (OK) { "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 accountId: 1000000200	HTTP status: 200 (OK) { "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 accountId: 2000000200	HTTP status: 200 (OK) { "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 accountId: 1234567890	HTTP status: 400 (Bad Request) { "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 accountId: 1234%3D5678	HTTP status: 400 (Bad Request) { "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 accountId: 0000000404	HTTP status: 404 (Not found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 Accept: application/vnd.hmrc.1.0	HTTP status: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/close-account

Close an existing LISA account

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 YYYY-MM-DD For example: 2017-05-20

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 ^[a-zA-Z0-9 :/-]{1,20}$
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 accountId: 1234567890	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 200 (OK) { "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 accountId: 1234567890	{ "accountClosureReason": "Cancellation", "closureDate": "2017-05-20" }	HTTP status: 200 (OK) { "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 accountId: 1234567890	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234%3D5678	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "closureDate": "3000" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-04-05" }	HTTP status: 403 (Forbidden) { "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 accountId: A1234560	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 403 (Forbidden) { "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 accountId: A1234561	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 403 (Forbidden) { "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 accountId: A1234568	{ "accountClosureReason": "Cancellation", "closureDate": "2017-05-20" }	HTTP status: 403 (Forbidden) { "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 accountId: A1234569	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 403 (Forbidden) { "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 accountId: A1234562	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 Accept: application/vnd.hmrc.1.0	{ "accountClosureReason": "All funds withdrawn", "closureDate": "2017-05-20" }	HTTP status: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/update-subscription

Modify date of first subscription of a LISA account

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 YYYY-MM-DD For example: 2017-05-20

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 ^[a-zA-Z0-9 :/-]{1,20}$
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 accountId: 1234567890	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 200 (OK) { "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 accountId: 1234567891	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 200 (OK) { "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 accountId: 1234567890	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234%3D5678	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "firstSubscriptionDate": "3000-01-01" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "firstSubscriptionDate": "2017-04-05" }	HTTP status: 403 (Forbidden) { "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 accountId: 0000000901	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 403 (Forbidden) { "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 accountId: 0000000903	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 403 (Forbidden) { "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 accountId: 0000000902	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 403 (Forbidden) { "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 accountId: 0000000404	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 Accept: application/vnd.hmrc.1.0	{ "firstSubscriptionDate": "2017-05-20" }	HTTP status: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }

Close section

Life events

Life events resources

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events

Report a death or terminal illness

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 YYYY-MM-DD For example: 2017-05-20

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 ^\d{10}$
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 accountId: 1234567890	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 201 (Created) { "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 accountId: 1234567890	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234%3D5678	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "eventType": "Invalid Event Type" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-05" }	HTTP status: 403 (Forbidden) { "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 accountId: 0000000403	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 403 (Forbidden) { "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 accountId: 1000000403	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 403 (Forbidden) { "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 accountId: 2000000403	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 403 (Forbidden) { "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 accountId: 3000000403	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 403 (Forbidden) { "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 accountId: 0000000404	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 404 (Not found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 Accept: application/vnd.hmrc.1.0	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }
Request containing an already reported event lisaManagerReferenceNumber: Use your test user profile accountId: 0000000409	{ "eventType": "LISA Investor Terminal Ill Health", "eventDate": "2017-04-20" }	HTTP status: 409 (Conflict) { "code": "LIFE_EVENT_ALREADY_EXISTS", "message": "The investor’s life event has already been reported", "lifeEventId": "1234567891" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/annual-returns

Send an annual return of information

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 YYYY-MM-DD For example: 2018-03-31
lisaManagerName string required	The name of the LISA provider. Must conform to the regular expression ^[a-zA-Z0-9 '/,&().-]{1,50}$ For example: Company Name
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 ^[0-9]{4}$ For example: 2018
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 ^[0-9]{1,6}$ For example: 1000
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 ^[0-9]{1,6}$ For example: 1000
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 ^[0-9]{1,4}$ For example: 100
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 ^[0-9]{1,4}$ For example: 100
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 ^\d{10}$
originalEventDate string required	The eventDate of the original return of information affected by the correction. Date in the format YYYY-MM-DD For example: 2018-03-31

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 ^\d{10}$
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 accountId: 1234567890	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "message": "Life event created", "lifeEventId": "7890000001" } }
Successfully corrected an annual return of information lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "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: 201 (Created) { "status": 201, "success": true, "data": { "message": "Life event superseded", "lifeEventId": "7890000002" } }
LISA manager reference number in the wrong format lisaManagerReferenceNumber: 123456 accountId: 1234567890	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }
Account ID in the wrong format lisaManagerReferenceNumber: Use your test user profile accountId: 1234%3D5678	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter accountId in the correct format, like ABC12345" }
Wrong or missing data lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "eventDate": "May 2018", "taxYear": "2018", "marketValueCash": 0, "marketValueStocksAndShares": 10.1, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 55, "annualSubsStocksAndShares": 0 }	HTTP status: 403 (Forbidden) { "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 accountId: 1234567890	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2016, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 403 (Forbidden) { "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 accountId: 1234567890	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 3000, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 403 (Forbidden) { "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 accountId: 2000000403	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED", "message": "The LISA account is already cancelled" }
Account void lisaManagerReferenceNumber: Use your test user profile accountId: 3000000403	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_VOID", "message": "The LISA account is already void" }
Account void lisaManagerReferenceNumber: Use your test user profile accountId: 1000000403	{ "eventDate": "2017-05-10", "lisaManagerName": "ISA Manager 1", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 56, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 403 (Forbidden) { "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 accountId: 5000000403	{ "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: 403 (Forbidden) { "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 accountId: 0000000404	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 404 (Not found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Accept header is missing or invalid lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 Accept: application/vnd.hmrc.1.0	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }
Life event already superseded lisaManagerReferenceNumber: Use your test user profile accountId: 1000000409	{ "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: 409 (Conflict) { "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 accountId: 0000000409	{ "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 }	HTTP status: 409 (Conflict) { "code": "LIFE_EVENT_ALREADY_EXISTS", "message": "The investor’s life event has already been reported", "lifeEventId": "7890000001" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/fund-releases

Request the release of funds to buy a property

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 YYYY-MM-DD For example: 2017-05-06
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: CR12345-6789
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 ^[A-Za-z0-9 :/-]{1,35}$ For example: Flat A
postalCode string required	The postcode of the property that you are requesting funds to buy. Must conform to the regular expression ^[A-Za-z0-9 ]{1,8}$ For example: AA1 1AA
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 ^\d{10}$ For example: 0987654321
originalEventDate string required	The eventDate of the fund release affected by the correction. Date in the format YYYY-MM-DD For example: 2017-05-06

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 ^\d{10}$
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: Use your test user profile accountId: 1234567890	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "message": "Fund release created", "lifeEventId": "3456789000" } }
Fund release superseded lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "eventDate": "2017-05-05", "withdrawalAmount": 5000.00, "supersede": { "originalLifeEventId": "3456789000", "originalEventDate": "2017-05-10" } }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "message": "Fund release superseded", "lifeEventId": "3456789001" } }
Invalid LISA Manager Reference Number lisaManagerReferenceNumber: 123456 accountId: 1234567890	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }
Invalid Account ID lisaManagerReferenceNumber: Use your test user profile accountId: 1234%3D5678	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter accountId in the correct format, like ABC12345" }
Submission has not passed validation lisaManagerReferenceNumber: 123456 accountId: 0000000405	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 400 (Invalid Payload) { "code": "INVALID_PAYLOAD", "message": "Submission has not passed validation" }
This LISA account is already closed lisaManagerReferenceNumber: Use your test user profile accountId: 1000000403	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_CLOSED", "message": "The LISA account is already closed" }
This LISA account is already void lisaManagerReferenceNumber: Use your test user profile accountId: 3000000403	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_VOID", "message": "The LISA account is already void" }
This LISA account is already cancelled lisaManagerReferenceNumber: Use your test user profile accountId: 2000000403	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED", "message": "The LISA account is already cancelled" }
Account not open long enough lisaManagerReferenceNumber: Use your test user profile accountId: 4000000403	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 403 (Forbidden) { "code": "COMPLIANCE_ERROR_ACCOUNT_NOT_OPEN_LONG_ENOUGH", "message": "The account has not been open for long enough" }
Other purchase on record lisaManagerReferenceNumber: Use your test user profile accountId: 6000000403	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 403 (Forbidden) { "code": "COMPLIANCE_ERROR_OTHER_PURCHASE_ON_RECORD", "message": "Another property purchase is already recorded" }
Supersede details do not match the original request lisaManagerReferenceNumber: Use your test user profile accountId: 5000000403	{ "eventDate": "2017-06-05", "withdrawalAmount": 10000.00, "supersede": { "originalLifeEventId": "3456789000", "originalEventDate": "2017-05-05" } }	HTTP status: 403 (Forbidden) { "code": "SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR", "message": "originalLifeEventId and the originalEventDate do not match the information in the original request" }
Invalid Data Provided lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 0000000404	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
The fund release you are superseding has already been superseded lisaManagerReferenceNumber: Use your test user profile accountId: 1000000409	{ "eventDate": "2017-05-05", "withdrawalAmount": 4000.00, "supersede": { "originalLifeEventId": "3456789000", "originalEventDate": "2017-05-10" } }	HTTP status: 409 (Conflict) { "code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED", "message": "This life event has already been superseded", "lifeEventId": "3456789001" }
Fund release already exists lisaManagerReferenceNumber: Use your test user profile accountId: 0000000409	{ "eventDate": "2017-05-10", "withdrawalAmount": 4000.00, "conveyancerReference": "CR12345-6789", "propertyDetails": { "nameOrNumber": "1", "postalCode": "AA11 1AA" } }	HTTP status: 409 (Conflict) { "code": "LIFE_EVENT_ALREADY_EXISTS", "message": "The investor’s life event has already been reported", "lifeEventId": "3456789000" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/purchase-extensions

Request a property purchase extension

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 ^\d{10}$ For example: 3456789000
eventDate string required	The date the extension is requested. This cannot be in the future. Date in the format YYYY-MM-DD For example: 2017-05-10
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 ^\d{10}$ For example: 6789000001
originalEventDate string required	The eventDate of the extension affected by the correction. Date in the format YYYY-MM-DD For example: 2017-05-11

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 ^\d{10}$
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 accountId: 1234567890	{ "fundReleaseId": "3456789001", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "message": "Extension created", "lifeEventId": "6789000001" } }
Superseded first purchase extension lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "eventDate": "2017-05-11", "eventType": "Extension one", "supersede": { "originalEventDate": "2017-05-10", "originalLifeEventId": "6789000001" } }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "message": "Extension superseded", "lifeEventId": "6789000002" } }
Second purchase extension lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "fundReleaseId": "3456789001", "eventDate": "2017-08-10", "eventType": "Extension two" }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "message": "Extension created", "lifeEventId": "6789000003" } }
Superseded second purchase extension lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "eventDate": "2017-08-11", "eventType": "Extension two", "supersede": { "originalEventDate": "2017-08-10", "originalLifeEventId": "6789000003" } }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "message": "Extension superseded", "lifeEventId": "6789000004" } }
Request with a valid payload and an invalid LISA Manager reference number lisaManagerReferenceNumber: 123456 accountId: 1234567890	{ "fundReleaseId": "3456789001", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234%3D5678	{ "fundReleaseId": "3456789001", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890	{ "eventDate": "10-05-2017", "eventType": "Extension 1" }	HTTP status: 400 (Bad Request) { "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 accountId: 1000000403	{ "fundReleaseId": "3456789001", "eventDate": "2017-08-10", "eventType": "Extension one" }	HTTP status: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_CLOSED", "message": "The LISA account is already closed" }
The LISA account is already cancelled lisaManagerReferenceNumber: Use your test user profile accountId: 2000000403	{ "fundReleaseId": "3456789001", "eventDate": "2017-08-10", "eventType": "Extension one" }	HTTP status: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED", "message": "The LISA account is already cancelled" }
The LISA account is already void lisaManagerReferenceNumber: Use your test user profile accountId: 3000000403	{ "fundReleaseId": "3456789001", "eventDate": "2017-08-10", "eventType": "Extension one" }	HTTP status: 403 (Forbidden) { "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 accountId: 7000000403	{ "fundReleaseId": "3456789001", "eventDate": "2017-08-10", "eventType": "Extension one" }	HTTP status: 403 (Forbidden) { "code": "FIRST_EXTENSION_NOT_APPROVED", "message": "A first extension has not yet been approved" }
First extension already approved lisaManagerReferenceNumber: Use your test user profile accountId: 8000000403	{ "fundReleaseId": "3456789001", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 403 (Forbidden) { "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 accountId: 9000000403	{ "fundReleaseId": "3456789001", "eventDate": "2017-08-10", "eventType": "Extension two" }	HTTP status: 403 (Forbidden) { "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 accountId: 5000000403	{ "eventDate": "2017-05-11", "eventType": "Extension one", "supersede": { "originalEventDate": "2017-05-10", "originalLifeEventId": "6789000001" } }	HTTP status: 403 (Forbidden) { "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 accountId: 0000000404	{ "fundReleaseId": "3456789001", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Fund release not found lisaManagerReferenceNumber: Use your test user profile accountId: 1000000404	{ "fundReleaseId": "3456789001", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 404 (Not Found) { "code": "FUND_RELEASE_NOT_FOUND", "message": "The fundReleaseId does not match HMRC’s records" }
Extension already exists lisaManagerReferenceNumber: Use your test user profile accountId: 0000000409	{ "fundReleaseId": "3456789001", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 409 (Conflict) { "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 accountId: 2000000409	{ "fundReleaseId": "3456789000", "eventDate": "2017-05-10", "eventType": "Extension one" }	HTTP status: 409 (Conflict) { "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 accountId: 1000000409	{ "eventDate": "2017-05-11", "eventType": "Extension one", "supersede": { "originalEventDate": "2017-05-10", "originalLifeEventId": "6789000001" } }	HTTP status: 409 (Conflict) { "code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED", "message": "This life event has already been superseded", "lifeEventId": "6789000002" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/purchase-outcomes

Report the outcome of a property purchase

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 ^\d{10}$ For example: 0987654321
eventDate string required	The date the outcome of the property purchase was known. This cannot be in the future. Date in the format YYYY-MM-DD For example: 2017-05-06
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 ^\d{10}$ For example: 0987654321
originalEventDate string required	The eventDate of the purchase outcome affected by the correction. Date in the format YYYY-MM-DD For example: 2017-05-06

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 ^\d{10}$
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: Use your test user profile accountId: 1234567890	{ "fundReleaseId": "3456789001", "eventDate": "2017-10-10", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000 }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "lifeEventId": "5678900001", "message": "Purchase outcome created" } }
Purchase outcome superseded lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "eventDate": "2017-10-05", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000, "supersede": { "originalLifeEventId": "5678900001", "originalEventDate": "2017-10-10" } }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "lifeEventId": "5678900002", "message": "Purchase outcome superseded" } }
Failed purchase outcome lisaManagerReferenceNumber: Use your test user profile accountId: 1234567891	{ "fundReleaseId": "3456789002", "eventDate": "2017-10-10", "propertyPurchaseResult": "Purchase failed" }	HTTP status: 201 (Created) { "status": 201, "success": true, "data": { "lifeEventId": "5678900003", "message": "Purchase outcome created" } }
Invalid LISA Manager Reference Number lisaManagerReferenceNumber: 123456 accountId: 1234567890	{ "fundReleaseId": "3456789001", "eventDate": "2017-10-10", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000 }	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }
Invalid Account ID lisaManagerReferenceNumber: Use your test user profile accountId: 1234%3D5678	{ "fundReleaseId": "3456789001", "eventDate": "2017-10-10", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000 }	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter accountId in the correct format, like ABC12345" }
Supersede details do not match the original request lisaManagerReferenceNumber: Use your test user profile accountId: 5000000403	{ "eventDate": "2017-10-05", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000, "supersede": { "originalLifeEventId": "5678900000", "originalEventDate": "2017-10-10" } }	HTTP status: 403 (Forbidden) { "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: Use your test user profile accountId: 1000000404	{ "fundReleaseId": "3456789001", "eventDate": "2017-10-10", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000 }	HTTP status: 404 (Not Found) { "code" : "FUND_RELEASE_NOT_FOUND", "message" : "The fundReleaseId does not match HMRC’s records" }
Investor account not found lisaManagerReferenceNumber: Use your test user profile accountId: 0000000404	{ "fundReleaseId": "3456789001", "eventDate": "2017-10-10", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000 }	HTTP status: 404 (Not found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
The purchase outcome you are superseding has already been superseded lisaManagerReferenceNumber: Use your test user profile accountId: 1000000409	{ "eventDate": "2017-10-05", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000, "supersede": { "originalLifeEventId": "5678900001", "originalEventDate": "2017-10-10" } }	HTTP status: 409 (Conflict) { "code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED", "message": "This life event has already been superseded", "lifeEventId": "5678900002" }
Purchase outcome already exists lisaManagerReferenceNumber: Use your test user profile accountId: 0000000409	{ "fundReleaseId": "3456789001", "eventDate": "2017-10-10", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000 }	HTTP status: 409 (Conflict) { "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: Use your test user profile accountId: 2000000409	{ "fundReleaseId": "3456789000", "eventDate": "2017-10-05", "propertyPurchaseResult": "Purchase completed", "propertyPurchaseValue": 250000 }	HTTP status: 409 (Conflict) { "code": "FUND_RELEASE_SUPERSEDED", "message": "This fund release has already been superseded", "lifeEventId": "3456789001" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/events/{lifeEventId}

View a life event

GET

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345
lifeEventId string required	The ID for the life event. Must conform to the regular expression ^\d{10}$ For example: 1234567890

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.

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 ^\d{10}$ For example: 0987654321
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 YYYY-MM-DD For example: 2017-05-20
lisaManagerName string optional	The name of the LISA provider. Must conform to the regular expression ^[a-zA-Z0-9 '/,&().-]{1,50}$ For example: Company Name
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 ^[0-9]{4}$ For example: 2018
marketValueCash integer optional	The total value that was reported for the cash LISA account. Must conform to the regular expression ^[0-9]{1,6}$ For example: 1000
marketValueStocksAndShares integer optional	The total value that was reported for the stocks and shares LISA account. Must conform to the regular expression ^[0-9]{1,6}$ For example: 1000
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 ^[0-9]{1,4}$ For example: 100
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 ^[0-9]{1,4}$ For example: 100
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: CR12345-6789
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 ^[A-Za-z0-9 :/-]{1,35}$ For example: Flat A
postalCode string required	The postcode of the property that you requested funds to buy. Must conform to the regular expression ^[A-Za-z0-9 ]{1,8}$ For example: AA1 1AA
fundReleaseId string optional	The ID of the fund release for an extension or purchase outcome. Must conform to the regular expression ^\d{10}$ For example: 0987654321
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 ^\d{10}$ For example: 0987654321
originalEventDate string required	The eventDate of the life event that was corrected. Date in the format YYYY-MM-DD For example: 2017-05-20
supersededBy string optional	The ID of the life event that supersedes the current one. Must conform to the regular expression ^\d{10}$ For example: 0987654321

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 accountId: 1234567890 lifeEventId: 1234567891	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 7890000001	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 7890000002	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 3456789000	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 3456789001	HTTP status: 200 (OK) [ { "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 accountId: 1234567891 lifeEventId: 3456789002	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 6789000001	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 6789000002	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 6789000003	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 6789000004	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 5678900001	HTTP status: 200 (OK) [ { "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 accountId: 1234567890 lifeEventId: 5678900002	HTTP status: 200 (OK) [ { "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 accountId: 1234567891 lifeEventId: 5678900003	HTTP status: 200 (OK) [ { "lifeEventId": "5678900003", "eventType": "Purchase outcome", "eventDate": "2017-10-10", "fundReleaseId": "3456789002", "propertyPurchaseResult": "Purchase failed" } ]
lisaManagerReferenceNumber is in the wrong format lisaManagerReferenceNumber: 123456 accountId: 1234567890 lifeEventId: 1234567891	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }
accountId is in the wrong format lisaManagerReferenceNumber: Use your test user profile accountId: 1234%3D5678 lifeEventId: 1234567891	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter accountId in the correct format, like ABC12345" }
Account not found lisaManagerReferenceNumber: Use your test user profile accountId: 0000000404 lifeEventId: 1234567891	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Life event not found lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 lifeEventId: 0000000404	HTTP status: 404 (Not Found) { "code": "LIFE_EVENT_NOT_FOUND", "message": "The lifeEventId does not match with HMRC’s records" }

Close section

Withdrawal charges

Withdrawal charges resources

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/withdrawal-charges

Report a withdrawal charge

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 YYYY-MM-DD For example: 2018-01-06
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 YYYY-MM-DD For example: 2018-02-05
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 ^\d{1,10}$ For example: 1234567890
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 ^\d{10}$
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: Use your test user profile accountId: 1234567890	{ "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: 201 (Created) { "status": 201, "success": true, "data": { "message": "Unauthorised withdrawal transaction created", "transactionId": "2345678901" } }
Unauthorised withdrawal transaction created - late notification lisaManagerReferenceNumber: Use your test user profile accountId: 1234567891	{ "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: 201 (Created) { "success": true, "status": 201, "data": { "transactionId": "2345678902", "message": "Unauthorised withdrawal transaction created - late notification" } }
Unauthorised withdrawal transaction superseded lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "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: 201 (Created) { "success": true, "status": 201, "data": { "transactionId": "2345678903", "message": "Unauthorised withdrawal transaction superseded" } }
Invalid and/or missing data lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "claimPeriodStartDate": 6, "claimPeriodEndDate": "1st May", "withdrawalAmount": 1000.001, "withdrawalChargeAmountYTD": 500.00, "fundsDeductedDuringWithdrawal": true, "withdrawalReason": "Regular withdrawal.", "automaticRecoveryAmount": 250.00 }	HTTP status: 400 (Bad Request) { "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: 123456 accountId: 1234567890	{ "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: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }
Invalid Account ID lisaManagerReferenceNumber: Use your test user profile accountId: 1234%3D5678	{ "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: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter accountId in the correct format, like ABC12345" }
Invalid monetary amounts and/or invalid dates lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 1000000403	{ "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: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED", "message": "The LISA account is already cancelled" }
This LISA account is already void lisaManagerReferenceNumber: Use your test user profile accountId: 2000000403	{ "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: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_VOID", "message": "The LISA account is already void" }
A superseded withdrawal report cannot be matched to the original lisaManagerReferenceNumber: Use your test user profile accountId: 3000000403	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 4000000403	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 5000000403	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 6000000403	{ "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: 403 (Forbidden) { "code": "WITHDRAWAL_REPORTING_ERROR", "message": "The withdrawal charge does not equal 25% of the withdrawal amount" }
Account ID does not exist lisaManagerReferenceNumber: Use your test user profile accountId: 0000000404	{ "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: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
The accept header is invalid lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 Accept: application/vnd.hmrc.1.0	{ "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: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }
Withdrawal charge has already been reported lisaManagerReferenceNumber: Use your test user profile accountId: 0000000409	{ "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: 409 (Conflict) { "code": "WITHDRAWAL_CHARGE_ALREADY_EXISTS", "message": "A withdrawal charge with these details has already been requested for this investor", "transactionId": "2345678901" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/withdrawal-charges/{transactionId}

Get details of a withdrawal charge

GET

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345
transactionId string required	The ID for the transaction. Must conform to the regular expression ^\d{1,10}$ For example: 1234567890

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.

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 YYYY-MM-DD For example: 2018-01-06
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 YYYY-MM-DD For example: 2018-02-05
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 ^\d{1,10}$ For example: 1234567890
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 ^\d{1,10}$ For example: 1234567890
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: Use your test user profile accountId: 1234567890 transactionId: 2345678901	{ "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: Use your test user profile accountId: 1234567890 transactionId: 2345678902	{ "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: Use your test user profile accountId: 1234567890 transactionId: 2345678903	{ "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: 123456 accountId: 1234567890 transactionId: 2345678901	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }
Invalid Account ID lisaManagerReferenceNumber: Use your test user profile accountId: 1234%3D5678 transactionId: 2345678901	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter accountId in the correct format, like ABC12345" }
Account ID does not exist lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 1000000404	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "accountId does not match HMRC’s records" }
Transaction ID does not exist lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 0000000404	HTTP status: 404 (Not Found) { "code": "WITHDRAWAL_CHARGE_TRANSACTION_NOT_FOUND", "message": "transactionId does not match HMRC’s records" }

Close section

Bonus requests

Bonus requests resources

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions

Request a bonus payment

POST

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345

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.

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 ^\d{10}$ For example: 0987654321
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 YYYY-MM-DD For example: 2017-05-06
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 YYYY-MM-DD For example: 2017-06-05
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 ^\d{1,10}$ For example: 1234567890
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 ^\d{10}$
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: Use your test user profile accountId: 1234567890	{ "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: 201 (Created) { "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: Use your test user profile accountId: 1234567891	{ "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: 201 (Created) { "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: Use your test user profile accountId: 1234567890	{ "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: 201 (Created) { "status": 201, "success": true, "data": { "message": "Bonus transaction created", "transactionId": "0003456789" } }
Superseded transaction - Bonus recovery lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "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: 201 (Created) { "status": 201, "success": true, "data": { "message": "Bonus transaction superseded", "transactionId": "0000456789" } }
Superseded transaction - Additional bonus lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890	{ "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: 201 (Created) { "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: 123456 accountId: 1234567890	{ "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: 400 (Bad Request) { "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 accountId: 1234%3D5678	{ "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: 400 (Bad Request) { "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 accountId: 1234567890	{ "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: 400 (Bad Request) { "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: Use your test user profile accountId: 1234567890	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 1234567890	{ "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: 403 (Forbidden) { "code": "LIFE_EVENT_NOT_PROVIDED", "message": "lifeEventId is required when the claimReason is a life event" }
Request containing invalid bonus payment figures lisaManagerReferenceNumber: Use your test user profile accountId: 0000000403	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 1000000903	{ "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: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_CLOSED", "message": "The LISA account is already closed" }
Request for an account that has already been voided lisaManagerReferenceNumber: Use your test user profile accountId: 2000000903	{ "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: 403 (Forbidden) { "code": "INVESTOR_ACCOUNT_ALREADY_VOID", "message": "The LISA account is already void" }
Request for an account that has already been cancelled lisaManagerReferenceNumber: Use your test user profile accountId: 3000000903	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 1234567890	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 1000000403	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 2000000403	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 3000000403	{ "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: 403 (Forbidden) { "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: Use your test user profile accountId: 1000000404	{ "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: 404 (Not Found) { "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: Use your test user profile accountId: 0000000404	{ "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: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Request for a bonus claim that has already been requested lisaManagerReferenceNumber: Use your test user profile accountId: 0000000409	{ "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: 409 (Conflict) { "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: Use your test user profile accountId: 1000000409	{ "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: 409 (Conflict) { "code": "BONUS_CLAIM_ALREADY_SUPERSEDED", "message": "This bonus claim has already been superseded", "transactionId": "0000456789" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 Accept: application/vnd.hmrc.1.0	{ "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: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions/{transactionId}

Get details of a bonus request

GET

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345
transactionId string required	The ID for the transaction. Must conform to the regular expression ^\d{1,10}$ For example: 1234567890

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.

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 ^\d{10}$ For example: 0987654321
periodStartDate string required	The first date in the claim period. Date in the format YYYY-MM-DD For example: 2017-05-06
periodEndDate string required	The end date of the claim period. Date in the format YYYY-MM-DD For example: 2017-06-05
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 ^\d{1,10}$ For example: 1234567890
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 ^\d{1,10}$ For example: 1234567890
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 accountId: 1234567890 transactionId: 0123456789	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": 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 accountId: 1234567890 transactionId: 0003456789	HTTP status: 200 (OK) { "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 accountId: 1234567890 transactionId: 0000456789	HTTP status: 200 (OK) { "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 accountId: 1234567890 transactionId: 0000056789	HTTP status: 200 (OK) { "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 accountId: 1234567890 transactionId: 0123456789	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" }
Request with an invalid accountId lisaManagerReferenceNumber: Use your test user profile accountId: 1234%3D5678 transactionId: 0123456789	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890 transactionId: 0000000404	HTTP status: 404 (Not Found) { "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 accountId: 1234567899 transactionId: 1000000404	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }

Close section

Payments and debts

Payments and debts resources

/lifetime-isa/manager/{lisaManagerReferenceNumber}/accounts/{accountId}/transactions/{transactionId}/payments

Get the payment details for a bonus claim or withdrawal charge

GET

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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 ^[a-zA-Z0-9 :/-]{1,20}$ For example: ABC12345
transactionId string required	The ID for the transaction. Must conform to the regular expression ^\d{1,10}$ For example: 1234567890

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.

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 ^\d{1,10}$
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 YYYY-MM-DD For example: 2017-05-20
paymentDueDate string optional	The date the payment is due. Date in the format YYYY-MM-DD For example: 2017-05-20
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 ^.{1,16}$ For example: 12345
paymentAmount number optional	The amount paid for the transaction. For example: 1000
supersededBy string optional	The ID of the transaction that supersedes the current one. Must conform to the regular expression ^\d{1,10}$

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 accountId: 1234567890 transactionId: 0123456789	HTTP status: 200 (OK) { "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 accountId: 1234567890 transactionId: 0000000200	HTTP status: 200 (OK) { "transactionId": "0000000200", "paymentStatus": "Pending" }
Request for a pending payment with a due date lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 3000000200	HTTP status: 200 (OK) { "transactionId": "3000000200", "transactionType": "Payment", "paymentStatus": "Pending", "paymentDueDate": "2017-06-20" }
Request for a cancelled transaction lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 1000000200	HTTP status: 200 (OK) { "transactionId": "1000000200", "paymentStatus": "Cancelled", }
Request for a void transaction lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 2000000200	HTTP status: 200 (OK) { "transactionId": "2000000200", "paymentStatus": "Void" }
Request for a debt which is due to be collected lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 2345678902	HTTP status: 200 (OK) { "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 accountId: 1234567890 transactionId: 2345678903	HTTP status: 200 (OK) { "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 accountId: 1234567890 transactionId: 2345678901	HTTP status: 200 (OK) { "transactionId": "2345678901", "paymentStatus": "Superseded", "supersededBy": "2345678903" }
Request to refund withdrawal charge has been cancelled lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 0000000403	HTTP status: 200 (OK) { "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 accountId: 1234567890 transactionId: 0123456789	HTTP status: 400 (Bad Request) { "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 accountId: 1234%3D5678 transactionId: 0123456789	HTTP status: 400 (Bad Request) { "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 accountId: 1234567890 transactionId: 0000000404	HTTP status: 404 (Not Found) { "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 accountId: 1234567899 transactionId: 1000000404	HTTP status: 404 (Not Found) { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile accountId: 1234567890 transactionId: 0123456789 Accept: application/vnd.hmrc.1.0	HTTP status: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }

Close section

/lifetime-isa/manager/{lisaManagerReferenceNumber}/payments

Get a list of all payments and debts in a date range

GET

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234

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 ^\d{4}-\d{2}-\d{2}$ For example: 2017-05-06
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 ^\d{4}-\d{2}-\d{2}$ For example: 2017-06-05

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.

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 ^Z([0-9]{4}|[0-9]{6})$ For example: Z1234
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: 23456
paymentReference string optional	Payment reference number. This will only be returned for paid payments and collected debts. Must conform to the regular expression ^.{1,35}$ For example: 1234567890
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 YYYY-MM-DD For example: 2017-05-20
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 YYYY-MM-DD For example: 2017-05-20

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 startDate: 2017-05-20 endDate: 2017-10-20	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" } ] }
Request for payments where none are found lisaManagerReferenceNumber: Use your test user profile startDate: 2017-04-06 endDate: 2017-04-06	HTTP status: 404 (Not Found) { "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: 400 (Bad Request) { "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 startDate: 20-05-2017 endDate: 2017-05-20	HTTP status: 400 (Bad Request) { "code": "BAD_REQUEST", "message": "startDate is in the wrong format" }
Request with endDate in the wrong format lisaManagerReferenceNumber: Use your test user profile startDate: 2017-05-20 endDate: 20-05-2017	HTTP status: 400 (Bad Request) { "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 startDate: 20-05-2017 endDate: 20-05-2017	HTTP status: 400 (Bad Request) { "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 startDate: (today's date) endDate: (any date in the future)	HTTP status: 403 (Forbidden) { "code": "FORBIDDEN", "message": "endDate cannot be in the future" }
Request with an endDate before the startDate lisaManagerReferenceNumber: Use your test user profile startDate: 2017-12-20 endDate: 2017-12-19	HTTP status: 403 (Forbidden) { "code": "FORBIDDEN", "message": "endDate cannot be before startDate" }
startDate cannot be before 6 April 2017 lisaManagerReferenceNumber: Use your test user profile startDate: 2017-04-05 endDate: 2017-04-06	HTTP status: 403 (Forbidden) { "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 startDate: 2017-04-06 endDate: 2018-04-07	HTTP status: 403 (Forbidden) { "code": "FORBIDDEN", "message": "endDate cannot be more than a year after startDate" }
Request with an invalid 'Accept' header lisaManagerReferenceNumber: Use your test user profile startDate: 2017-04-06 endDate: 2017-05-05 Accept: application/vnd.hmrc.1.0	HTTP status: 406 (Not Acceptable) { "code": "ACCEPT_HEADER_INVALID", "message": "The accept header is missing or invalid" }

Close section

Skip to main content

Is this page not working properly? Is this page not working properly?