leehawksworth/self-assessment-api

Self-Assessment API

This REST API allows clients to post information related to a taxpayer, and then get an estimated tax liability calculation for a tax period.

A typical workflow would be:

1. Authenticate.
2. Access a self-assessment resource (this is implicitly created).
3. Send details of various income sources (e.g. employment or property).
4. Send details of various types of summary (e.g. income or expenses) for each source.
5. Request a liability calculation.
6. Wait for calculation to complete (only a short time).
7. Request calculation and display it to your user.

All end points are User Restricted (see authorisation). Versioning, data formats etc follow the API Platform standards (see the reference guide).

The API makes use of HATEOAS/HAL resource links. Your application does not need to store a catalogue of all URLs.

Sources and summaries will be given IDs. Do not expect these to be GUIDs. They will only be unique within context. I.e. source IDs will be unique for that type of source and within that self-assessment. Similarly, summary IDs will be unique for that type of summary within its source.

You will need to store these IDs within your application for disambiguation and reconciliation.

Consider:

• We do not expect or want you to submit transaction level information (if fact, we may limit the amount of data you can send). How will you aggregate this information within your software?
• How does your application deal with lost HTTP requests or responses?
• How do you reconcile your data with our data?
• The API doesn't expose meta-data or audit information (e.g. created or update times, who made the change). Do you need to record this audit information yourself?
• Your application may not be the only application access and modifying a taxpayer's data. How would you differentiate different data from your application and others?

You can dive deeper into the documentation in the API Developer Hub.

Running Locally

Install Service Manager, if you want live endpoints, then start dependencies:

sm --start MONGO
sm --start AUTH -f
sm --start DATASTREAM -f

Start the app:

sbt run -Drun.mode=Dev

Now you can test sandbox:

curl -v http://localhost:9000/sandbox/$UTR -H 'Accept: application/vnd.hmrc.1.0+json'

License

This code is open source software licensed under the Apache 2.0 License