Sunrise API Integration Guide

This document will guide you through the process of opening a connection to the Sunrise Integration API. To use this API, you will require a client ID, which your Sunrise administrator can provide. This ID is effectively your password to use the API, and so it should be well-guarded.


To begin, you will need to obtain the authorization token from the server; this will be used as the key to authorize all future requests. Using cURL:

curl -X POST \
  --data "grant_type=password&client_id=<your client ID>"

Assuming that your ID is valid, you will receive JSON similar to the following:

  "access_token": "<token>",
  "token_type": "bearer",
  "expires_in": 1799

If your ID is incorrect, you will see something like this:

  "error": "invalid_clientId",
  "error_description":"Invalid client_id '<your client ID>'"

You will need to store the access_token value for later. Keep this secure - this is like your key-card for getting into the API. Note that the expires_in value is in seconds - once the token expires, you will need to call the oauth2/token URL again to obtain a fresh token.

Once you have obtained a valid token, you can use it to authorize subsequent API calls. Using cURL:

curl -i \
  -H "Authorization: Bearer <your token>" \

Testing the API

The Sunrise API makes two methods available for checking that the API is available, and that your credentials are valid:

The first method is designed to check that the API server is up and running - it will return HTTP 200 if so. It does not require any authorization.

The second method tests your authorization token. Using cURL:

curl -i \
  -H "Authorization: Bearer <your token>" \

This should return:

HTTP 200 "success"

Using other technologies

The Sunrise Public API can be used with any programming or scripting language that supports HTTP. These are some sample scripts for a few of them:

JavaScript (using JQuery)

var authToken = "";
var data = { grant_type: 'password', client_id: '{{your client ID}}' };
$.getJSON("", data, function (response) {
    authToken = response.access_token;

    // you can now use the auth token
        url: "",
        type: "GET",
        headers: {
            Authorization: "bearer " + authToken
    }.done(function (data) {
        // ...
}).fail(function () {
    alert("Invalid client ID");



# get the auth token
$postParams = @{

$result = Invoke-RestMethod -Uri "" -Method Post -Body $postParams
$AuthToken = $result.access_token;

# now we can use the auth token
$headers = @{
    Authorization="bearer $AuthToken"

$result = Invoke-RestMethod -Uri "" -Method Get -Headers $headers

# this will print a hash-table of contact details for 'bob'
Write-Host $result