Suran API Information

Overview

Suran API is a RESTful API for integrating into Suran products such as CDM+. Responses are formatted in JSON and encoded in UTF-8.

Availability

Suran API is available to:

All CDM+ SAAS plans (including Essentials)
The traditional Cloud plan

Testing

Contact our support team to request a test/sandbox environment for your organization.

Endpoints

View available endpoints and their documentation at api.suran.com.

Authentication

There are two types of API integration, each with its own style of authentication:

SYSTEM calls are not specific to a user and only require a single token, called a Provision Code, to authenticate.

SESSION calls are used to perform multiple operations as a specific authenticated user. These calls require:

A Provision Code and PIN to authenticate
Local cookie storage to manage session data

Each endpoint is labelled with its type in the documentation.

Credentials

See How to find API Credentials for steps to locate the Provision and PIN for your CDM+ database.

Examples

System Endpoints

Pass the provision code as a Provision header to system calls. Follow the steps under How to find API Credentials to locate the provision code.

Here is an example query:

BASH

# should succeed with valid provision
curl -X POST \
  -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' \
  -d 'testparam=foo' \
  'https://api.suran.com/api/v2/authenticated_test_system'

# response
# HTTP Status: 200
{
    "data": "test successful"
}

# should fail without provision
curl -X POST \
  -d 'testparam=foo' \
  'https://api.suran.com/api/v2/authenticated_test_system'

# response
{
	"errors": [
		{
			"error": "Provision header required", 
			"status": 422
		}
	]
}

Session Endpoints

Working with session endpoints in Suran API is a three-step process:

Log in with a provision and PIN to start an authenticated session.
Query the relevant endpoint(s) according to specified documentation.
Log out to close the authenticated session.

For session endpoints you will need a provision code and a PIN. Follow the steps under How to find API Credentials to locate the provision code and PIN. You will also need to store and pass cookies with each call.

Here is an example login, query, and logout of a session:

BASH

# log in
curl -X POST \
  -c cookies.txt -b cookies.txt \
  -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' \
  -d 'provision=2524a545-58bc-426d-9802-f3cca41ebc8e&pin=2222' \
  'https://api.suran.com/api/v2/login'

# should succeed when logged in
curl -X POST \
  -c cookies.txt -b cookies.txt \
  -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' \
  -d 'testparam=foo' \
  'https://api.suran.com/api/v2/authenticated_test_session'

# response
# HTTP Status: 200
{
    "data": "test successful. individual_id: 111, provision: "
}

# log out
curl -X DELETE \
  -c cookies.txt -b cookies.txt \
  -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' \
  'https://api.suran.com/api/v2/logout'

# should fail after logging out
curl -X POST \
  -c cookies.txt -b cookies.txt \
  -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' \
  -d 'testparam=foo' \
  'https://api.suran.com/api/v2/authenticated_test_session'

# response
{
    "errors": [
        {
            "error": "You are not logged in",
            "status": 422
        }
    ]
}