Attach challenge case evidence

This endpoint allows a user to attach evidence supporting a challenge case.

Attaching evidence is a two-step process:

1. Call this endpoint and supply fileName, mimeType and - optionally - redirect URLs in the body of the request
2. Upload the evidence file as a multi-part form using the form fields contained in the response from Step 1

Note: We recommend that the response fields are not hardcoded as these are subject to change.

Step 1

Request

POST /my-organisation/challenge-cases/{challengeSubmissionId}/evidence HTTP/1.1 Authorization: Bearer ... Content-Type: application/json Accept: application/vnd.hmrc.2.0+json

{ "fileName": "some_file.jpg", "mimeType": "image/jpeg", "successRedirect": "http://example.com/success", "errorRedirect": "http://example.com/error" }

Response

{ "reference": "533bedac-914a-474e-86d2-753d0b18f4bb", "uploadRequest": { "href": "https://www.upscan.tax.service.gov.uk", "fields": { "x-amz-meta-callback-url": "https://api.service.hmrc.gov.uk/business-rates-attachments/callback", "x-amz-date": "20180611T081926Z", "x-amz-credential": "ASIAxxxxxxxxx/20180202/eu-west-2/s3/aws4_request", "x-amz-algorithm": "AWS4-HMAC-SHA256", "key": "533bedac-914a-474e-86d2-753d0b18f4bb", "acl": "private", "x-amz-signature": "xxxx", "Content-Type": "image/jpeg", "policy": "eyJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMTAyNDAwLDIwOTcxNTIwXV19", "success_action_redirect": "http://example.com/success", "error_action_redirect": "http://example.com/error" } } }

Step 2

In order to upload the file, the following multipart-form is sent as the body of a POST request which should contain all the fields and values returned in "fields" map in the response above and no other fields.

POST https://www.upscan.tax.service.gov.uk/v1/uploads/fus-inbound-8a7204a4f7373185b08ff170fdbfc676 Content-Type: multipart/form-data; boundary=WebAppBoundary

--WebAppBoundary Content-Disposition: form-data; name="x-amz-credential"

AKIAILMNXN5U2SUOUNHQ/20201021/eu-west-2/s3/aws4_request --WebAppBoundary Content-Disposition: form-data; name="x-amz-meta-upscan-initiate-response"

2020-10-21T19:22:02.700Z --WebAppBoundary Content-Disposition: form-data; name="x-amz-meta-original-filename"

${filename} --WebAppBoundary Content-Disposition: form-data; name="x-amz-algorithm"

AWS4-HMAC-SHA256 --WebAppBoundary Content-Disposition: form-data; name="x-amz-signature"

5bfc0ee8596491a29df9a41dc1f507ef11e380cb4a746515517f8fb597e61026 --WebAppBoundary Content-Disposition: form-data; name="Content-Type"

application/pdf --WebAppBoundary Content-Disposition: form-data; name="x-amz-meta-session-id"

n/a --WebAppBoundary Content-Disposition: form-data; name="x-amz-meta-callback-url"

https://business-rates-attachments.protected.mdtp/business-rates-attachments/callback --WebAppBoundary Content-Disposition: form-data; name="x-amz-date"

20201021T192202Z --WebAppBoundary Content-Disposition: form-data; name="x-amz-meta-upscan-initiate-received"

2020-10-21T19:22:02.699Z --WebAppBoundary Content-Disposition: form-data; name="x-amz-meta-request-id"

s46529b8e-20f9-4343-871c-29a85bdcf909 --WebAppBoundary Content-Disposition: form-data; name="key"

a05f47b5-2aac-41fd-bdf4-2b564d751aee --WebAppBoundary Content-Disposition: form-data; name="acl"

private --WebAppBoundary Content-Disposition: form-data; name="x-amz-meta-consuming-service"

business-rates-attachments --WebAppBoundary Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjoiMjAyMC0xMC0yOFQxOToyMjowMi42OTlaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZnVzLWluYm91bmQtOGE3MjA0YTRmNzM3MzE4NWIwOGZmMTcwZmRiZmM2NzYifSx7ImFjbCI6InByaXZhdGUifSx7IngtYW16LWNyZWRlbnRpYWwiOiJBS0lBSUxNTlhONVUyU1VPVU5IUS8yMDIwMTAyMS9ldS13ZXN0LTIvczMvYXdzNF9yZXF1ZXN0In0seyJ4LWFtei1hbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In0seyJrZXkiOiJhMDVmNDdiNS0yYWFjLTQxZmQtYmRmNC0yYjU2NGQ3NTFhZWUifSx7IngtYW16LWRhdGUiOiIyMDIwMTAyMVQxOTIyMDJaIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMSwxMDQ4NTc2MF0seyJ4LWFtei1tZXRhLWNhbGxiYWNrLXVybCI6Imh0dHBzOi8vYnVzaW5lc3MtcmF0ZXMtYXR0YWNobWVudHMucHJvdGVjdGVkLm1kdHAvYnVzaW5lc3MtcmF0ZXMtYXR0YWNobWVudHMvY2FsbGJhY2sifSx7IngtYW16LW1ldGEtY29uc3VtaW5nLXNlcnZpY2UiOiJidXNpbmVzcy1yYXRlcy1hdHRhY2htZW50cyJ9LHsieC1hbXotbWV0YS1yZXF1ZXN0LWlkIjoiczQ2NTI5YjhlLTIwZjktNDM0My04NzFjLTI5YTg1YmRjZjkwOSJ9LHsieC1hbXotbWV0YS11cHNjYW4taW5pdGlhdGUtcmVjZWl2ZWQiOiIyMDIwLTEwLTIxVDE5OjIyOjAyLjY5OVoifSx7IngtYW16LW1ldGEtc2Vzc2lvbi1pZCI6Im4vYSJ9LFsic3RhcnRzLXdpdGgiLCIkeC1hbXotbWV0YS1vcmlnaW5hbC1maWxlbmFtZSIsIiJdLFsic3RhcnRzLXdpdGgiLCIkeC1hbXotbWV0YS11cHNjYW4taW5pdGlhdGUtcmVzcG9uc2UiLCIiXSx7IkNvbnRlbnQtVHlwZSI6ImFwcGxpY2F0aW9uL3BkZiJ9XX0= --WebAppBoundary Content-Disposition: form-data; name="file"

...

N.B. names of the individual parts of the multipart form must be wrapped in double quotes and any whitespace around the equals sign is not permitted. E.g. each part should be formatted like this:

Content-Disposition: form-data; name="x-amz-meta-request-id"

and not like this:

Content-Disposition: form-data; name = x-amz-meta-request-id

Or, the POST request could be made via a web form:

<form method="POST" href="...value of the href from the response above..."> <input type="hidden" name="x-amz-algorithm" value="AWS4-HMAC-SHA256"> ... all the fields returned in "fields" map in the response above ... <input type="file" name="file"/> <- form field representing the file to upload <input type="submit" value="OK"/> </form>

Notes

The response to your file upload will be a HTTP 303 redirect to one of the URLs you may have provided in Step 1.

If the upload was successful, you will be redirected to the successRedirect URL. If you did not provide a successRedirect in Step 1, the response will be a 204 No Content.

If the upload failed, you will be redirected to the errorRedirect URL. Details about the nature of the error will be appended to the errorRedirect URL in the form of query parameters. If you did not provide an errorRedirect in Step 1, we will respond with the failure status code and a JSON body describing the error. The error document returned will have these fields: key, errorCode, errorMessage, errorResource, and errorRequestId. All fields are optional and of type String.

Whichever way the form is sent:

• Use multipart encoding (multipart/form-data) NOT application/x-www-form-urlencoded. If you use application/x-www-form-urlencoded, AWS will return a response from which this error is not clear.
• The 'file' field must be the last field in the submitted form.

File names must not be blank and must not include certain forbidden characters, such as em-dashes, asterisks, question marks, colons, etc (for actual regex refer to the published JSON schema of the request)

Currently, the only MIME types supported are:

• application/msword
• application/vnd.openxmlformats-officedocument.wordprocessingml.document
• application/vnd.ms-excel
• application/vnd.ms-excel.sheet.binary.macroEnabled.12
• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• application/vnd.oasis.opendocument.formula
• application/pdf
• image/jpeg

The following file size restrictions are in place:

• Minimum file size: 1B
• Maximum file size: 10MB