This version is in beta - expect some breaking changes.

Lifetime ISA API

Dates and amounts
Date Amount
Version and status
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

Path parameters table
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

Request headers Table
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"]}
  }
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
  }
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
  }
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
  }
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
  }
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
  }
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
    }
  }
]

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
  }
}

Request table
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
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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"
}

Response table
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

Error scenarios table
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

Path parameters table
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

Request headers Table
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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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"
  }
}

Request table
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
}

Response table
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

Error scenarios table
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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
   "totalSubsYTD": 4000.00
 },
 "bonuses": {
   "bonusPaidYTD": 0.0,
   "bonusDueForPeriod": 1000.00,
   "totalBonusDueYTD": 1000.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": 4000.00,
   "totalSubsYTD": 4000.00
 },
 "bonuses": {
   "bonusPaidYTD": 0.0,
   "bonusDueForPeriod": 1000.00,
   "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1050.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1050.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1050.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1050.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1050.00,
    "totalBonusDueYTD": 1000.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": 4000.00,
    "totalSubsYTD": 4000.00
  },
  "bonuses": {
    "bonusPaidYTD": 0.0,
    "bonusDueForPeriod": 1000.00,
    "totalBonusDueYTD": 1000.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

Path parameters table
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

Request headers Table
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": 4000,
    "totalSubsYTD": 4000
  },
  "bonuses": {
    "bonusPaidYTD": 0,
    "bonusDueForPeriod": 1000,
    "totalBonusDueYTD": 1000,
    "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"
  }
}

Response table
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

Error scenarios table
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": 4000,
    "totalSubsYTD": 4000
  },
  "bonuses": {
    "bonusPaidYTD": 0,
    "bonusDueForPeriod": 1000,
    "totalBonusDueYTD": 1000,
    "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": 4000,
    "totalSubsYTD": 4000
  },
  "bonuses": {
    "bonusPaidYTD": 0,
    "bonusDueForPeriod": 1000,
    "totalBonusDueYTD": 1000,
    "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

Path parameters table
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

Request headers Table
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"
}

Response table
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

Error scenarios table
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

Path parameters table
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

Query parameters table
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

Request headers Table
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"
    }
  ]
}

Response table
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