Feature/write api import

_source/_layouts/default.haml

@@ -81,6 +81,10 @@
                       %a{href: '/channel.html'} Channel
                     %li
                       %a{href: '/sign_out.html'} Sign Out
+                    %li
+                      %a{href: '/score.html'} Score
+                    %li
+                      %a{href: '/import.html'} Import
 
                 %li.nav-header
                   Notes on

_source/alias.haml

@@ -168,7 +168,7 @@ title: Alias
 
   %h3 Return Value
 
-  %p When alias returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
+  %p When alias returns you will receive an object with the following structure. This response means your request was successfully received and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
 
   %code.json.spread
     :escaped

_source/annotate.haml

@@ -102,7 +102,7 @@ title: Annotate
 
 %h3#return Return Value
 
-%p When annotate returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
+%p When annotate returns you will receive an object with the following structure. This response means your request was successfully received and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
 
 %code.json
   :escaped

_source/authentication.haml

@@ -4,17 +4,17 @@ title: Authentication
 
 %h2 Authentication
 
-%p You authenticate to the Trak.io API by providing your API token in the request. You can find your API token in your account.
+%p You authenticate to the Trak.io API by providing your API token or API secret key in the request. You can find your API token and API secret key in your account settings.
 
 %h3 Expired Trials
 
-%p If you account doesn't have a paid subscription and is out of the 14 free trial (plus an additional 28 day grace period) your request will be rejected with a <a href='/errors.html'>402 error</a>
+%p If your account doesn't have a paid subscription and is out of the 14 day free trial (plus an additional 28 day grace period) your request will be rejected with a <a href='/errors.html'>402 error</a>
 
 %div.for-javascript
 
   %h3.first JavaScript
 
-  %p When using the JavaScript library you just can set the your API token once and it will be used for all subsequent API calls.
+  %p When using the JavaScript library you just can set your API token and it will be used for all subsequent API calls to send data to Trak.io.
 
   %code.javascript
     :escaped
@@ -24,21 +24,41 @@ title: Authentication
 
   %h3.first HTTP
 
-  %p When accessing the HTTP end points directly you should send your API token with each request in a query parameter named 'token'.
+  %p When accessing the HTTP end points directly to send data you should send your API token with each request in a query parameter named 'token'. When retrieving data you should send your API secret key with each request in a query parameter named 'key'.
+
+  %h4 Sending data
 
   %code.bash
     :escaped
       $ curl https://api.trak.io/v1/identify \
         --data token='YOUR_API_TOKEN'\
         --data data='{"distinct_id": "12346789", "properties": { "name": "Matthew Spence" }}'
 
-  %p You can also send your API token as a HTTP header if you like.
+  %h4 Retrieving data
+
+  %code.bash
+    :escaped
+      $ curl https://api.trak.io/v1/score \
+        --data key='YOUR_API_SECRET_KEY'\
+        --data distinct_id='12346789'
+
+  %p You can also send your API token or API secret key as a HTTP header if you like.
+
+  %h4 Sending data
 
   %code.bash
     :escaped
       $ curl https://api.trak.io/v1/identify \
         --header "X-Trakio-Token: YOUR_API_TOKEN" \
         --data data='{"distinct_id": "12346789", "properties": { "name": "Matthew Spence" }}'
 
+  %h4 Retrieving data
+
+  %code.bash
+    :escaped
+      $ curl https://api.trak.io/v1/score \
+        --header "X-Trakio-Key: YOUR_API_SECRET_KEY" \
+        --data distinct_id="12346789"
+
   %p.note
-    Providing your token in the header <code>X-Token</code> is depreciated, but still supported for backwards compatibility.
+    Providing your token in the header <code>X-Token</code> or your key in the header <code>X-Key</code> is depreciated, but still supported for backwards compatibility.

_source/background_processing.haml

@@ -5,22 +5,23 @@ title: Background Processing
 %h2 Background Processing
 
 %p
-  <strong>When the Trak.io API recieves a request it is not processed immediately.</strong> It is
+  <strong>Most Trak.io API requests are not processed immediately.</strong> It is
   validated and stored in a queue for processing by a background processor.
   Under normal conditions the background worker will process the request within a
-  second or two of being recieved.
+  second or two of being received. Requests to retrieve data are not queued and are
+  processed immediately.
 
 %p
   This ensures we can respond to API request as quickly as possible and adds a
-  layer of redundency that ensures we can continue to recieve and respond promptly to your
+  layer of redundency that ensures we can continue to receive and respond promptly to your
   API requests during periods of unusually high traffic or while we are having
   technical difficulties.
 
 %h3 Validation of Your Requests
 
 %p
   Before requests are queued for processing they are validated to predict any problems
-  that may arise during processing. This allows us to respond with the relavent <a href='errors.html'>error
+  that may arise during processing. This allows us to respond with the relevant <a href='errors.html'>error
   codes</a> when the request is made.
 
 %p
@@ -31,7 +32,7 @@ title: Background Processing
 %p.note
   Whilst we aim to have all of our services up all of the time, the realities of technlogy,
   means we need to pepare for having parts of our system unavailable. <strong>Having
-  our API up to recieve your data</strong> regardless of the status of our other systems
+  our API up to receive your data</strong> regardless of the status of our other systems
   <strong>is our number one priority</strong>.
 
 %h3 "The Benefit of the Doubt"

_source/company.haml

@@ -218,7 +218,7 @@ title: Company
 #return
   %h3 Return Value
 
-  %p When company returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
+  %p When company returns you will receive an object with the following structure. This response means your request was successfully received and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
 
   %code.json.spread
     :escaped

_source/errors.haml

@@ -11,13 +11,16 @@ title: Errors
   %li <code>DataObjectInvalidBase64</code> - the encoded data object provided was missing or invalid url safe base64
   %li <code>DataObjectInvalidType</code> - the data value provided was not an object
   %li <code>InvalidToken</code> - API token was either missing or invalid
+  %li <code>InvalidKey</code> - API secret key was either missing or invalid
   %li <code>MissingParameter</code> - you missed a required data parameter
   %li <code>RouteNotFound</code> - You requested an end point that doesn't exist
   %li <code>PropertiesObjectInvalid</code> - the properties object provided was invalid
   %li <code>RequestInvalidJson</code> - when <a href='/http.html#full-json'>sending the request as JSON</a> the body was invalid JSON
   %li <code>RevenuePropertyInvalid</code> - revenue property for an event was not a float, integer or string
   %li <code>TrialExpired</code> - your account's free trial (including an additional 28 day grace period) has expired
   %li <code>InternalServiceError</code> - any other error will raise this, it usual means we did something wrong instead of you
+  %li <code>PersonNotFound</code> - You provided a distinct_id that doesn't exist
+  %li <code>CompanyNotFound</code> - You provided a company_id that doesn't exist
 
 .for-http
 
@@ -29,7 +32,7 @@ title: Errors
     %li <code>200</code> - OK, everything worked as expected.
     %li <code>202</code> - accepted, the request was accepted and stored for <a href='/background_processing.html'>background processing</a> but may be rejected later if it is invalid
     %li <code>400</code> - bad request, missing a required parameter, or incorrect format
-    %li <code>401</code> - unauthorized, missing or invalid API token
+    %li <code>401</code> - unauthorized, missing or invalid API token/secret key
     %li <code>402</code> - payment required, your account's free trial has expired (including a 28 day grace period)
     %li <code>404</code> - not found, the requested method or item doesn't exist
     %li <code>500</code>, <code>502</code>, <code>503</code>, <code>504</code> - server errors, these are on us :(
@@ -40,7 +43,7 @@ title: Errors
     :escaped
       {
         "status": "error",
-        "code": 401, # repeats the HTTP status code, usefull if using the force_200 argument
+        "code": 401, # repeats the HTTP status code, useful if using the force_200 argument
         "exception": "TrakioAPI::Exceptions::InvalidToken", # The exception class raised
         "message": "Missing or invalid API token.", # The message for the raised exception
         "details": "You must povide a valid API token, see http://docs.tra.io/authentication.html." # Additional details for the specific error
@@ -50,11 +53,11 @@ title: Errors
 
   %h3.first JavaScript
 
-  %p When the JavaScript library encounters one of the above exceptions it will throw an equivilent JavaScript error.
+  %p When the JavaScript library encounters one of the above exceptions it will throw an equivalent JavaScript error.
 
 .for-ruby
 
   %h3.first Ruby
 
-  %p When the Ruby library recieves one of the above response exceptions it will raise an equivilent Ruby exception.
+  %p When the Ruby library receives one of the above response exceptions it will raise an equivalent Ruby exception.
 

_source/http.haml

@@ -6,11 +6,13 @@ title: HTTP API Introduction
 
 %p
   :markdown
-    The Trak.io HTTP API endpoint is at `https://api.trak.io/v1/` and supports three actions all of which are avaliable with `POST` and `GET` requests.
+    The Trak.io HTTP API endpoint is at `https://api.trak.io/v1/`.
 
 %p.note
   The HTTP API supports both HTTP and HTTPS, however <strong>we strongly recommend you only use HTTPS</strong> when connecting. All Trak.io's API libraries use HTTPS.
 
+%h3 Sending data to Trak.io
+
 %ul
   %li
     %a{href: '/identify.html#http'} POST\GET https://api.trak.io/v1/identify
@@ -20,8 +22,10 @@ title: HTTP API Introduction
     %a{href: '/track.html#http'} POST\GET https://api.trak.io/v1/track
   %li
     %a{href: '/annotate.html#http'} POST\GET https://api.trak.io/v1/annotate
+  %li
+    %a{href: '/import.html#http'} POST\GET https://api.trak.io/v1/import
 
-%p Any request expects the following, as url parameters when sending a GET request or as form data when sending a POST request:
+%p Any request to the endpoints listed above expects the following, as url parameters when sending a GET request or as form data when sending a POST request:
 
 %table.table.spread
   %thead
@@ -52,7 +56,7 @@ title: HTTP API Introduction
       %th force_200
       %td Boolean
       %td 0, 1 if callback provided
-      %td You can force a 200 status code by setting force_200 to true, this is designed specifically so that if you are using JSONP and there is an error you can still recieve the data.
+      %td You can force a 200 status code by setting force_200 to true, this is designed specifically so that if you are using JSONP and there is an error you can still receive the data.
     %tr
       %th img
       %td Boolean
@@ -64,12 +68,35 @@ title: HTTP API Introduction
       %td null
       %td If destination is set, after the request has been performed it will redirect to the destination, this is helpful for example, when you wish to track someone clicking a link.
 
+%h3 Retrieving data from Trak.io
+
+%ul
+  %li
+    %a{href: '/score.html#http'} GET https://api.trak.io/v1/score
+
+%p Any request to the endpoints listed above expects the following as url parameters when sending a GET request:
+
+%table.table.spread
+  %thead
+    %tr
+      %th Parameter
+      %th Type
+      %th Default
+      %th Description
+  %tbody
+    %tr
+      %th key
+      %td String
+      %td
+        %em Required
+      %td Your API secret key can be found in your account settings and verifies your account for retrieving data.
+
 %h3#full-json Sending Requests As JSON
 
-%p You can send the above request parameters as encoded JSON, as apposed to GET parameters or POST form data, by setting your `Content-Type` request HTTP header to `application/json`.
+%p You can send the request parameters as encoded JSON, as apposed to GET parameters or POST form data, by setting your `Content-Type` request HTTP header to `application/json`.
 
 %code.bash.spread
   :escaped
     $ curl https://api.trak.io/v1/track \
       --header "Content-Type: application/json" \
-      --data '{"token":"YOUR_API_TOKEN", "data":{"distinct_id": 12346789, "event": "Page view", "channel": "Web site", "properties": { "title": "Matts Home Page" }, "context": { "time_zone": "GMT" }}}'
+      --data '{"token":"YOUR_API_TOKEN", "data":{"distinct_id": 12346789, "event": "Page view", "channel": "Web site", "properties": { "title": "Matts Home Page" }, "context": { "time_zone": "GMT" }}}'

_source/identify.haml

@@ -261,7 +261,7 @@ title: Identify
 #return
   %h3 Return Value
 
-  %p When identify returns you will recieve an object with the following structure. This response means your request was successfully recieved and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
+  %p When identify returns you will receive an object with the following structure. This response means your request was successfully received and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
 
   %code.json.spread
     :escaped

_source/import.haml

@@ -0,0 +1,118 @@
+---
+title: Import
+---
+
+%h2 Import
+
+%p Import is how you record batches of events performed by people or companies.
+
+%p.note Batches greater than 2500 event objects will be rejected and invalid event objects will not be processed.
+
+#javascript.for-javascript
+
+  %h3.first JavaScript
+
+  %p Coming soon!
+
+#ruby.for-ruby
+
+  %h3.first Ruby
+
+  %p Coming soon!
+
+#http.for-http
+
+  %h3.first HTTP
+
+  %p A raw HTTP call to <code>api.trak.io/v1/import</code> has certain requirements and options as outlined in the <a href='/http.html'>introduction to the HTTP API</a>. In addition data specific to the import action should be sent in the data parameter as a JSON string.
+
+  %code.bash.spread
+    :escaped
+      $ curl -v -XPOST \
+        --data token=YOUR_API_TOKEN \
+        --data data='{
+          events: {
+            "event": "Page view",
+            "distinct_id": "12346789"
+            "channel": "Web site",
+            "properties": {},
+            "context": { "time_zone": "GMT" }
+          },{
+            "event": "Page view",
+            "company_id": "987654321",
+            "channel": "Web site",
+            "properties": {},
+            "context": { "time_zone": "GMT" }
+          }' \
+        https://api.trak.io/v1/import
+
+  %h4 Data Object
+
+  %table.table.spread
+    %thead
+      %tr
+        %th Property
+        %th Type
+        %th Default
+        %th Description
+    %tbody
+      %tr#http-argument-distinct-id
+        %th events
+        %td Array
+        %td
+          %em Required
+        %td A list of event objects you wish to import.
+
+  %h4 Event Object
+
+  %table.table.spread
+    %thead
+      %tr
+        %th Property
+        %th Type
+        %th Default
+        %th Description
+    %tbody
+      %tr#http-argument-distinct-id
+        %th distinct_id
+        %td String
+        %td
+          %em Required, unless <code><a href='#http-argument-company-id'>company_id</a></code> is provided
+        %td The distinct ID of the person you wish to register this event against.
+      %tr#http-argument-company-id
+        %th company_id
+        %td String
+        %td
+          %em Required, unless <code><a href='#http-argument-distinct-id'>distinct_id</a></code> is provided
+        %td The company ID of the company you wish to register this event against.
+      %tr
+        %th event
+        %td String
+        %td
+          %em Required
+        %td The key for this event, this value will be <a href='/data_keys.html'>standardized server side</a>.
+      %tr
+        %th channel
+        %td String
+        %td web_site
+        %td The channel this event occurred in.
+      %tr
+        %th properties
+        %td Object
+        %td {}
+        %td A set of key value <a href='/properties.html#event'>properties</a> that help describe the event.
+      %tr#time
+        %th time
+        %td String (ISO 8601)
+        %td
+          %em Now
+        %td The time that this event occurred, the time should be a string formatted in <a href='http://en.wikipedia.org/wiki/ISO_8601' target='_blank'>ISO 8601</a>.
+
+#return
+  %h3 Return Value
+
+  %p When track returns you will receive an object with the following structure. This response means your request was successfully received and queued for <a href='/background_processing.html'>proccessing</a>. Under normal conditions this will happen asyncronously within a second or two.
+
+  %code.json
+    :escaped
+      { "status": "success" }