Send an annual return of information

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.

Test data

<table style="font-family:Roboto, sans-serif; font-size:14px;"> <col width="25%"> <col width="35%"> <col width="40%"> <thead> <tr> <th>Scenario</th> <th>Request Payload</th> <th>Response</th> </tr> </thead> <tbody> <tr> <td>Successfully sent an annual return of informationlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234567890</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">201 (Created)</code> <pre class="code--block"> { "status": 201, "success": true, "data": { "message": "Life event created", "lifeEventId": "7890000001" } } </pre> </td> </tr> <tr> <td>Successfully corrected an annual return of informationlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234567890</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 65, "annualSubsCash": 0, "annualSubsStocksAndShares": 65, "supersede": { "originalLifeEventId": "7890000001", "originalEventDate": "2018-04-05" } } </pre> </td> <td>HTTP status: <code class="code--slim">201 (Created)</code> <pre class="code--block"> { "status": 201, "success": true, "data": { "message": "Life event superseded", "lifeEventId": "7890000002" } } </pre> </td> </tr> <tr> <td>LISA manager reference number in the wrong formatlisaManagerReferenceNumber: 123456 accountId: 1234567890</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">400 (Bad Request)</code> <pre class="code--block"> { "code": "BAD_REQUEST", "message": "Enter lisaManagerReferenceNumber in the correct format, like Z1234" } </pre> </td> </tr> <tr> <td>Account ID in the wrong formatlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234%3D5678</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">400 (Bad Request)</code> <pre class="code--block"> { "code": "BAD_REQUEST", "message": "Enter accountId in the correct format, like ABC12345" } </pre> </td> </tr> <tr> <td>Wrong or missing datalisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234567890</td> <td> <pre class="code--block"> { "eventDate": "May 2018", "taxYear": "2018", "marketValueCash": 0, "marketValueStocksAndShares": 10.1, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">400 (Bad Request)</code> <pre class="code--block"> { "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" } ] } </pre> </td> </tr> <tr> <td>A mixture of cash and stocks and shares in the same annual returnlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234567890</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 55, "annualSubsStocksAndShares": 0 } </pre> </td> <td>HTTP status: <code class="code--slim">403 (Forbidden)</code> <pre class="code--block"> { "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" } ] } </pre> </td> </tr> <tr> <td>Tax year before 2017lisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234567890</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2016, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">403 (Forbidden)</code> <pre class="code--block"> { "code": "FORBIDDEN", "message": "There is a problem with the request data", "errors": [ { "code": "INVALID_DATE", "message": "The taxYear cannot be before 2017", "path": "/taxYear" } ] } </pre> </td> </tr> <tr> <td>Tax year in the futurelisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234567890</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 3000, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">403 (Forbidden)</code> <pre class="code--block"> { "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" } ] } </pre> </td> </tr> <tr> <td>Account cancelledlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 2000000403</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">403 (Forbidden)</code> <pre class="code--block"> { "code": "INVESTOR_ACCOUNT_ALREADY_CANCELLED", "message": "The LISA account is already cancelled" } </pre> </td> </tr> <tr> <td>Account voidlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 3000000403</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">403 (Forbidden)</code> <pre class="code--block"> { "code": "INVESTOR_ACCOUNT_ALREADY_VOID", "message": "The LISA account is already void" } </pre> </td> </tr> <tr> <td>Account voidlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1000000403</td> <td> <pre class="code--block"> { "eventDate": "2017-05-10", "lisaManagerName": "ISA Manager 1", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 56, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">403 (Forbidden)</code> <pre class="code--block"> { "code": "INVESTOR_ACCOUNT_ALREADY_CLOSED", "message": "The LISA account is already closed" } </pre> </td> </tr> <tr> <td> Supersede details do not match the original return of information lisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 5000000403 </td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 65, "annualSubsCash": 0, "annualSubsStocksAndShares": 65, "supersede": { "originalLifeEventId": "7890000001", "originalEventDate": "2018-04-04" } } </pre> </td> <td>HTTP status: <code class="code--slim">403 (Forbidden)</code> <pre class="code--block"> { "code": "SUPERSEDED_LIFE_EVENT_MISMATCH_ERROR", "message": "originalLifeEventId and the originalEventDate do not match the information in the original request" } </pre> </td> </tr> <tr> <td>Account could not be foundlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 0000000404</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">404 (Not found)</code> <pre class="code--block"> { "code": "INVESTOR_ACCOUNTID_NOT_FOUND", "message": "Enter a real accountId" } </pre> </td> </tr> <tr> <td>Accept header is missing or invalidlisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1234567890 Accept: application/vnd.hmrc.1.0</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">404 (Not Found)</code> <pre class="code--block"> { "code": "MATCHING_RESOURCE_NOT_FOUND", "message": "A resource with the name in the request can not be found in the API" } </pre> </td> </tr> <tr> <td> Life event already superseded lisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 1000000409 </td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 65, "annualSubsCash": 0, "annualSubsStocksAndShares": 65, "supersede": { "originalLifeEventId": "7890000001", "originalEventDate": "2018-04-05" } } </pre> </td> <td>HTTP status: <code class="code--slim">409 (Conflict)</code> <pre class="code--block"> { "code": "SUPERSEDED_LIFE_EVENT_ALREADY_SUPERSEDED", "message": "This life event has already been superseded", "lifeEventId": "7890000002" } </pre> </td> </tr> <tr> <td>Life event already existslisaManagerReferenceNumber: <a href="/api-documentation/docs/api/service/lisa-api/2.0#testing">Use your test user profile</a> accountId: 0000000409</td> <td> <pre class="code--block"> { "eventDate": "2018-04-05", "lisaManagerName": "Company Name", "taxYear": 2018, "marketValueCash": 0, "marketValueStocksAndShares": 55, "annualSubsCash": 0, "annualSubsStocksAndShares": 55 } </pre> </td> <td>HTTP status: <code class="code--slim">409 (Conflict)</code> <pre class="code--block"> { "code": "LIFE_EVENT_ALREADY_EXISTS", "message": "The investor’s life event has already been reported", "lifeEventId": "7890000001" } </pre> </td> </tr> </tbody> </table>

lisaManagerReferenceNumberstring required

Example:Z1234

The reference given to the LISA provider when they applied for approval from HMRC.

accountIdstring required

Example:ABC12345

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.

Accept'application/vnd.hmrc.2.0+json' required

Specifies the response format and the version of the API to be used.

Content-Type'application/json' required

Specifies the format of the request body, which must be JSON.

Authorizationstring required

Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with appropriate scope.

Request body

eventDatestring required

The date the return of information is sent. This cannot be in the future.

lisaManagerNamestring required

The name of the LISA provider.

taxYearinteger 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.

marketValueCashinteger 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.

marketValueStocksAndSharesinteger 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.

annualSubsCashinteger 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.

annualSubsStocksAndSharesinteger 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.

Example request

{
  "eventDate": "2018-03-31",
  "lisaManagerName": "Company Name",
  "taxYear": 2018,
  "marketValueCash": 1000,
  "marketValueStocksAndShares": 1000,
  "annualSubsCash": 100,
  "annualSubsStocksAndShares": 100,
  "supersede": {
    "originalEventDate": "2018-03-31"
  }
}

Response

Created

statusnumber required

The HTTP status of the result of the API call. Always 201.

successboolean required

Whether the API call was successful or not. Always true.

v1

Send an annual return of information

Test data

Path parameters

Headers

Request body

Example request

Response