This document is intended to be used by developers who are using the VTS Agent API to generate and manage appeals. This document consists of an explanation of how an agent will set up an account to be able to make calls to the API and gives an overview of what methods are available in the API itself.
\nTo start using the VTS AgentAPI, first you need to -
\nYou must use a valid API Key to send requests to the API endpoints.
\nThe API has rate and usage limits.
\nThe API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources.
\nThe API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key.
\nAPI access rate limits apply at a per-API key basis in unit time. The limit is 50 seperate requests per minute. If you exceed either limit, your request will return an HTTP 429 Too Many Requests status code.
\nEach API response returns the following set of headers to help you identify your use status:
\nAn HTTP 503 response from our servers indicates there is an unexpected spike in API access traffic.
The Developer portal allows end users (consumers) of the API to sign up for access to a self-service portal from which they can generate their own access credentials.
\nThe portal can be accessed by using the Developer Portal URL above:
\nThe VTS Agent API uses a subscription key for authentication.
\nYou must include an API key in each request to the API with the X-Api-Key request header.
\nBelow we will list out the steps in order to obtain subscription key in order to use the API.
\nFirstly, if you haven't recieved an email then you must email Appeals@valuationtribunal.gov.uk requesting access.
\nYou will receive an email to sign-up and create an account on the Developer portal.
\nThere you will set your password.
\nNext log into the developer portal in the url which was listed above.
\nThen select the Products tab.
\nNext enter a name for subscription. This should be the name of your company.
\nBelow are the various API methods available with the VTS Agent API. This API is used in order to submit appeals to the valuation tribunual services.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"1. Introduction","slug":"1-introduction"},{"content":"2. Initial Set Up","slug":"2-initial-set-up"},{"content":"3 Authentication","slug":"3-authentication"}],"owner":"33403375","collectionId":"026b62f4-c0bd-44e9-816d-84260d29a22f","publishedId":"2sA2xiVWmW","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF0000"},"publishDate":"2024-04-09T13:24:49.000Z"},"item":[{"name":"Create an Appeal","event":[{"listen":"test","script":{"id":"f0062708-af14-4080-8d87-df06e4a0fcd8","exec":[""],"type":"text/javascript","packages":{}}}],"id":"dacf1556-69c1-49ad-ad89-9175d068c5a3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Ocp-Apim-Subscription-Key","value":"The first method is a HTTP Post request in order to create an appeal. Below are examples of the response from the api. Some points to consider:
\n• If IsRepresentingOwner is true the appeal will be created against an owner, if false it will be created for an occupier.
• Your reference, Address line 1, Address Town and Address Post code, billing authority code, appellant email and appellant last name are mandatory.
• Billing authority code is a number.
• To create an organisation name, use the Appellant Last name and leave Appellant first name blank.
• “RatepayerIsKnown” is mandatory. If “RatepayerIsKnown” is true, then the “RatepayerFullName”, “RatepayerAddressLine1”, “RatepayerAddressPostCode” and “RatepayerAddressTown” fields also become mandatory.
There are also field constraints for the API, however these are not enforced by the API. The field constraints are:
\nThe address fields should be 100 characters or less
\nPostcode is 8 characters or less
\nName field is 160 characters or less (Note the name field is a combination of the first name and last name in the appeal packet)
\nThe next example is using the HTTP Post request in order to add a document. Only certain document types are allowed for this. The document binary data must be base 64 encoding and passed via the DocumentData property Only the following types are currently permitted “pdf, doc, docx”. A test is made that the document is valid for this extension and has a valid extension in the filename. Document type can be 1 or 3. 1 represents a decision, 3 represents evidence.
\n","urlObject":{"protocol":"https","path":["AgentAPI-Dev","v2","AddDocument"],"host":["api","valuationtribunal","gov","uk"],"query":[],"variable":[]}},"response":[{"id":"0096fde6-257c-43cb-bd7d-35028e8f49be","name":"Successful Appeal","originalRequest":{"method":"POST","header":[{"key":"Ocp-Apim-Subscription-Key","value":"The GET request is used in order to get the status of your appeals. You can either get all appeals associated with your subscription key or just get a unique appeal based on the appeal ID. You also have the option to see how much information you get about the appeals. These are all seen in the examples below.
\n","urlObject":{"protocol":"https","path":["AgentAPI-Dev","v2","AppealStatus"],"host":["api","valuationtribunal","gov","uk"],"query":[],"variable":[]}},"response":[{"id":"35760636-c68a-4ed8-9e5a-f8eeeebcec23","name":"Get All Appeal Status","originalRequest":{"method":"GET","header":[{"key":"Ocp-Apim-Subscription-Key","value":"Next is the POST request which is used in order the submit your appeal for processing. This requires that two different documents are attached one for document type 1 and another for 3. Below is an example of a succesful appeal, as well as incorrect formats for submitting an appeal.
\n","urlObject":{"protocol":"https","path":["AgentAPI-Dev","v2","SubmitAppealForProcessing"],"host":["api","valuationtribunal","gov","uk"],"query":[],"variable":[]}},"response":[{"id":"51725aa7-c218-4c42-bf9d-8513d9850b71","name":"Successful Submission","originalRequest":{"method":"POST","header":[{"key":"Ocp-Apim-Subscription-Key","value":"The final POST request allows you to update an appeal. Here you will need the unique appeal ID and reference. These will be supplied in the body of the request, where you can change alter information associated with your appeal. All other properties are optional – only those entered will be updated.
\nSimilarly to when creating an appeal there are the following field restrictions:
\nThe address fields should be 100 charracters or less
\nPostcode is 8 characters or less
\nName field is 160 characters or less (Note the name field is a combination of the first name and last name in the appeal packet)
\n