Merge pull request #8 from hmrc/RAS-200

RAS-200 | RAS-204 | Updated documentation content based on content re…

resources/public/api/conf/1.0/application.raml

@@ -1,7 +1,7 @@
 #%RAML 1.0
 ---
 
-title: Relief-At-Source
+title: Customer information for businesses API
 version: 1.0
 protocols: [ HTTPS ]
 baseUri: http://api.service.hmrc.gov.uk
@@ -26,17 +26,12 @@ types:
     type: string
     pattern: "^[0-9A-Fa-f]{8}(-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}$"
     example: "6b853b58-625f-4e64-955e-43a7cdff5c03"
-  FinancialYearType :
-    type : string
-    pattern : "^\\d{4}-\\d{2}$"
-    example : "2016-17"
-
 
 /customer:
       /match:
             post:
               is: [headers.acceptHeader, headers.contentHeader]
-              displayName: Check Customer records
+              displayName: Search HMRC’s records for a customer
               description: !include documentation/customer.match
               (annotations.scope): "write:hmrcmatch"
               securedBy: [ sec.oauth_2_0: { scopes: [ "write:hmrcmatch" ] } ]
@@ -120,26 +115,22 @@ types:
       /matched:
             /{customer-uuid}:
               description: |
-                Used as a temporary URL to access via GET, the root data for
-                a matched customer.  The URL is returned only from a matching action
-                using the POST to the /match path described above.  The URL is only
-                valid for a limited period of time.  After expiry a 404 will be
-                returned if accessed.
-              displayName: Supports GET of link data for a matched customer for a
-                limited period of time.
+                Returns a URL you can use to check a customer’s information. Currently, the only check available is to
+                check if the customer is a Scottish taxpayer.
+
+                The URL is only valid for a limited period of time. After expiry a 404 will be returned if accessed.
+              displayName: Check a customer’s information
               uriParameters:
                 customer-uuid:
                   type: UUID
                   example: "6b853b58-625f-4e64-955e-43a7cdff5c03"
               get:
                 description: |
-                  Used as a temporary URL to access via GET, the root data for
-                  a matched customer.  The URL is returned only from a matching action
-                  using the POST to the /match path described above.  The URL is only
-                  valid for a limited period of time.  After expiry a 404 will be
-                  returned if accessed.
-                displayName: Supports GET of link data for a matched customer for a
-                  limited period of time.
+                  Returns a URL you can use to check a customer’s information. Currently, the only check available is to
+                  check if the customer is a Scottish taxpayer.
+
+                  The URL is only valid for a limited period of time. After expiry a 404 will be returned if accessed.
+                displayName: Check a customer’s information
                 responses:
                   200:
                     body:
@@ -159,25 +150,26 @@ types:
                       The match (POST to /match) will need to repeated.
 
               /get-residency-status:
-                description: Get the residency status for the matched customer
-                  for the requested financial year
-                displayName: Get the residency status for the matched customer
+                description: Check if the customer is resident in Scotland for tax purposes.
+
+                             If you’re a pension scheme administrator, you need to know this to make the correct
+                             relief at source claims.
+                displayName: Check if a customer is a Scottish resident
                 get:
-                  queryParameters:
-                    financial-year:
-                      type: FinancialYearType
-                      example: "2016-17"
+                  description: Check if the customer is resident in Scotland for tax purposes.
 
+                               If you’re a pension scheme administrator, you need to know this to make the correct
+                               relief at source claims.
+                  displayName: Check if a customer is a Scottish resident
                   responses:
                     200:
                       body:
                         application/json:
                           type: !include schemas/getResidencyStatus.schema.json
                           example: |
                             {
-                              "financialYear" : "2015/16",
-                              "UKResidencyStatus" : "RUK",
-                              "confidenceStatus" : "confirmed"
+                              "currentYearResidencyStatus" : "otherUKResident",
+                              "nextYearForecastResidencyStatus" : "scotResident"
                             }
                     403:
                       description:

resources/public/api/conf/1.0/documentation/customer.match

@@ -1 +1,3 @@
-API call to verify a customer has matching record with HMRC
+Search HMRC’s records for a customer by their name, date of birth and National Insurance number.
+
+A successful search will return a link you can use to check a customer’s information.

resources/public/api/conf/1.0/documentation/overview.md

@@ -1,10 +1,10 @@
 
 
-This API allows financial organisations to validate and retrieve tax status information against HM Revenue and Customs (HMRC) records.
+Use this API to check HMRC's records and find out information about your customers.
 
 This version of the API is in development and is very likely to change.
 
-The current API allows the financial organisation to:
+Currently, the current API only allows a financial organisation to:
 
-  * match a customer record with HMRC    
-  * request a relief-at-source status after the customer information has been matched.    
+  * match a customer with HM Revenue and Customs (HMRC) records   
+  * check if a customer is a Scottish resident    

resources/public/api/conf/1.0/schemas/getResidencyStatus.schema.json

@@ -1,38 +1,24 @@
 {
-	"$schema": "http://json-schema.org/draft-04/schema#",
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type" : "object",
   "properties":
   {
-    "financialYear" : {"$ref" : "#/definitions/FinancialYearType"},
-    "UKResidencyStatus"  : {"$ref" : "#/definitions/UKResidencyStatusType"},
-    "confidenceStatus"  : {"$ref" : "#/definitions/ConfidenceStatusType"}
+    "currentYearResidencyStatus"  : {"$ref" : "#/definitions/UKResidencyStatusType"},
+    "nextYearForecastResidencyStatus"  : {"$ref" : "#/definitions/UKResidencyStatusType"}
   },
   "additionalProperties": false,
   "required" :
   [
-    "financialYear", "UKResidencyStatus", "confidenceStatus"
+    "currentYearResidencyStatus", "nextYearForecastResidencyStatus"
   ],
   "definitions" :
   {
-    "FinancialYearType" :
-    {
-      "type" : "string",
-      "pattern" : "^\\d{4}\/\\d{2}$"
-    },
     "UKResidencyStatusType" :
     {
       "type" : "string",
       "enum" :
       [
-        "GB-SCT", "RUK"
-      ]
-    },
-    "ConfidenceStatusType" :
-    {
-      "type" : "string",
-      "enum" :
-      [
-        "confirmed", "indicative"
+        "scotResident", "otherUKResident"
       ]
     }
   }