Getting Started

Get an account

Before you can use the API you will need an account. If you don't already have an account get in touch with us at info@streetstream.net

Start making requests

While testing your integrations you'll want to use the sandbox url until you're ready to switch to the production url

Authorise

Before you can start submitting jobs you'll need to get an OAuth token. To do that you'll need to send a POST request to /authorise like this:

curl -H "Authorization: Basic dGVzdEB0ZXN0LmNvbTp0ZXN0MTIzNA==" --data "grant_type=client_credentials" "https://sandbox-api.streetstream.co.uk/authorise"

The Authorization header token is your account email and password joined by a : and base64 encoded, like this:

base64_encode("test@test.com:test1234")
// dGVzdEB0ZXN0LmNvbTp0ZXN0MTIzNA==

If all goes well you should get a response from the server that looks like this:

{
    "code":200,
    "result":
        {
            "access_token":"5Y/OdvHuT6R3DjjKTOcNJ33c7Ajql+iy2MxK5l41tU8=",
            "token_type":"Bearer",
            "expires_in":86400
        }
    }

For all future requests set your Authorization header like this:

Authorization: Bearer YOUR_ACCESS_TOKEN_HERE
//e.g. Authorization: Bearer 5Y/OdvHuT6R3DjjKTOcNJ33c7Ajql+iy2MxK5l41tU8=

Getting an Estimate

Before submitting a job, you may wish to get an estimate for the job from the api. To get an estimate, all you need to provide is the pickup postcode and dropoff postcode, and the weight in kilograms. Depending on the weight you provide, an appropriate courier class will be selected for estimation and delivery.

Submitting a Job, Courier Availability And Job Acceptance

Once you're authenticated and have your Bearer token, you can go ahead and let your customer choose to have their goods delivered with Street Stream's same day courier service. To do that you'll need to submit a job on our system with all the details by sending a POST request to /v3/jobs. The request body should be a json object in the following format:

{
    "label" : "My Delivery Job",
    "pickup" : {
        "contactNumber" : "020 7754 5452",
        "contactName" : "Jane Doe",
        "postCode" : "SW8 1NL",
        "county" : "",
        "city" : "London",
        "address2" : "11 Claylands Place",
        "address1" : "A Company HQ"
    },
    "clientTag" : "My Customer",
    "notes" : "Any delivery details",
    "isImmediate" : true,
    "dropoff" : {
        "contactNumber" : "",
        "contactName" : "S Holmes",
        "postCode" : "NE1 6XE",
        "county" : "",
        "city" : "London",
        "address2" : "",
        "address1" : "221b Baker Street"
    },
    "weight" : 7,
    "largeVanRequired" : false,
    "signatureRequired" : false,
    "type" : "FixedRateJob",
    "pickupTime" : {
        "from" : "2016-09-05T14:30:00.000Z",
        "to" : "2016-09-05T15:00:00.000Z"
    },
    "autoAccept" : true
}

We will automatically calculate the delivery cost based on the job distance and your rates and return that with the updated job details. We will also calculate the delivery window based on the pickup window and the travel time. It is your responsibility to make sure that you don't submit jobs that would result in a delivery window later than your agreed working hours. If you submit a job outside of the hours you have agreed with Street Stream there is a greater likelihood of the job failing to be taken by a courier.

If the job is submitted succesfully you will receive a response like this:

{
  "code": 200,
  "result": {
    "autoQuoteValue": 26.4,
    "travelTime": 1743,
    "depth": 20,
    "height": 30,
    "width": 42,
    "packageType": "medium-package",
    "expires": "2016-09-05T14:00:00.000Z",
    "label": "My Delivery Job",
    "customer": {
      "company": "A Company",
      "id": "57bef7500239aa010071154c",
      "firstname": "John",
      "lastname": "Smith",
      "email": "js@acompany.co.uk",
      "telephone": null,
      "registered": "2016-08-25T13:49:04+00:00",
      "disabled": null,
      "userType": "Customer",
      "fullname": "John Smith"
    },
    "pickup": {
      "longitude": -0.1140628,
      "latitude": 51.48107839999999,
      "address1": "A Company HQ",
      "address2": "11 Claylands Place",
      "city": "London",
      "county": "",
      "postCode": "SW8 1NL",
      "contactName": "Jane Doe",
      "contactNumber": "020 7754 5452"
    },
    "clientTag": "My Customer",
    "notes": "Any delivery details",
    "isImmediate": true,
    "dropoff": {
      "longitude": -0.1585385,
      "latitude": 51.5237715,
      "address1": "221b Baker Street",
      "address2": "",
      "city": "London",
      "county": "",
      "postCode": "NE1 6XE",
      "contactName": "S Holmes",
      "contactNumber": ""
    },
    "weight": 7,
    "largeVanRequired": false,
    "signatureRequired": false,
    "__t": "FixedRateJob",
    "quotes": [],
    "pickupTime": {
      "from": "2016-09-05T14:30:00.000Z",
      "to": "2016-09-05T15:00:00.000Z"
    },
    "submitted": "2016-09-13T14:09:16.241Z",
    "paymentRetries": 0,
    "status": "PENDING",
    "ignoredBy": [],
    "distance": 8.2,
    "paymentMultiplier": 1,
    "vouchers": [],
    "autoAccept": true,
    "_id": "57d8088cb5b1c60f0067ef03",
    "deliveryAttempts": 1,
    "deliveryDeadline": {
      "to": "2016-09-05T15:30:00.000Z",
      "from": "2016-09-05T14:50:00.000Z"
    }
  }
}

And that's it, we will handle auto accepting the job. We will select the best quote after 3 minutes, or immediately after once we receive one. If there are no quotes within 3 minutes we will actively get involved to engage couriers to ensure one quotes for you. It is possible we will cancel the job if there are no quotes before the end of your pickup window. If this occurs, we will cancel the job and let you know that there has been a problem. As long as your submitting jobs within your agreed window with James, this shouldn't happen but you'll need to know how to handle it just in case.

Status Updates

To keep you up to date with the state of your job we will send you POST requests to webhook urls that you can specify to us.

Each url you give us will receive a x-www-form-urlencoded POST request with event and data parameters. The event parameter will be a string that denotes what event has taken place to trigger the webhook i.e. Job.Updated or Job.Cancelled, which are the main two you'll want to look out for. The data parameters contains an array with any relevant data, so for instance, when a quote has been accepted you'll receive a webhook with a request body like this:

event=Job.StatusChanged&data[job]=57d2c22fac955b01003d5821&data[status]=COLLECTED

The job and status parameters will always be present. Certain webhooks may also include relevant data. For instance;

Quote Accepted

event=Job.QuoteAccepted&data[job]=57d2c22fac955b01003d5821&data[quote]=57d2c22fac955b01003d581a&data[status]=QUOTE ACCEPTED&data[courier][name]=Philip J Fry&data[courier][email]=jd@planet-express.co.uk&data[courier][telephone]=01912286555&data[courier][transport]=van

Delivered

event=Job.StatusChanged&data[job]=57d2c22fac955b01003d5821&data[status]=DELIVERED&data[deliveryDetails][notes]=Delivered without incident&data[deliveryDetails][address]=742 Evergreen Terrace, Springfield&data[deliveryDetails][recipient]=Homer Simpson&data[deliveryDetails][condition]=Checked&data[deliveryDetails][signature]=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAARgAAADSCAYAAACRit/qAADFFklEQVR4nOy9d...

The optional signature parameter on deliveryDetails contains a base64 encoded string representation of the recipient's signature.


The available event actions that can be hooked into are as follows:


Configuration

If you need to you can get the current example rates and the postcodes covered by Street Stream by sending a GET request to /v3/config