Doc changes

docs/index.md

@@ -1,6 +1,6 @@
-About this documentation
+About this document
 ==========================
-This documentation is for developers, technical architects, and service managers who want to use the GOV.UK Notify platform to send notifications to users of their digital service. 
+This document is for developers, technical architects, and service managers who want to use the GOV.UK Notify platform to send notifications to users of their digital service. 
 
 About GOV.UK Notify
 ====================
@@ -32,7 +32,7 @@ To get started:
 
   At first your service will be in trial mode. When you’re fully integrated and ready to go live, send a request to the GOV.UK Notify team. 
 
-3. From the dashboard, add templates to be able to send sms and email notifications. You can personalise the template using double brackets for replaceables. For example: 
+3. Add a template to be able to send sms and email notifications. You can personalise the template using double brackets for replaceables. For example: 
 
   Dear ((name))
 
@@ -40,13 +40,26 @@ To get started:
 
 4. Upload a csv file containing the list of recipients and replaceables. 
 5. Send an sms or email notification.
-6. Create a new API key. This will be used for ???.
+6. Create a new API key. This will be used to connect to the API.
+
+  You can provide all your developers with test keys so they can experiment in the Sandbox environment. But keep the number of keys for real integrations to a minimum number of people on your team. 
+
 
 
 
 Integrate the GOV.UK API into your service
 ============================================
 
+A client (on github) will make calls to GOV.UK Notify on your behalf. 
+
+You can either:
+* use the user client library provided by Notify - there is currently 1 python library but more will be added in different languages.
+* develop your own ???
+
+To make an IPA call to a client you need:
+* the service ID - this is aviailable on the API keys page on the GOV.UK Notify interface
+* an API key - this is a secret key so save it somewhere safe; do not commit keys to public source code repositories
+
 API integration
 ------------------
 
@@ -54,6 +67,63 @@ API integration
 API endpoints
 ----------------
 
+You can use the API to:
+* send notifications
+* retrieve one or more notifications
+* retrieve all notifications
+
+To send a text notification:
+```
+POST /notifications/sms
+```
+
+```
+{
+  'to': '+447700900404',
+  'template': 1
+}
+```
+Where ‘to’ is the phone number and ‘template’ is the template ID to send.
+
+The response will be:
+```
+{
+   'data':{
+      'notification': {
+         'id':1
+      }
+   }
+}
+```
+To get the status of a text notification:
+```
+GET /notifications/{id}
+```
+
+```
+{
+   'data':{
+      'notification': {
+         'status':'sent',
+         'createdAt':'2016-01-01T09:00:00.999999Z',
+         'to':'+447827992607',
+         'method':'sms',
+         'sentAt':'2016-01-01T09:01:00.999999Z',
+         'id':1,
+         'message':'...',
+         'jobId':1,
+         'sender':'sms-partner'
+      }
+   }
+}
+```
+
+
+
+
+
+
+
 
 Functional testing
 ---------------------