Introduction

Welcome to Self Management Group’s Assessment API documentation. The SMG Assessment API allows you to gain access to the assessment tools offered by the Self Management Group. Key functions are made available for consumers to integrate our assessment tools into your custom applications.

Our Assessment API is RESTful. Each request has an associated HTTP verb which must be used. Certain endpoints accept resources and/or posted data as part of the request.

All requests must be made via SSL (HTTPS), and non-SSL requests will be ignored. Each request requires authorization through the use of bearer tokens.

The Assessment API base URL is at the following location: https://www.selfmgmt.com/api/v1

Authorization

In order to authorize your API queries, you will need to create a token using your set of public and private keys (currently supplied to you by Self Management Group).

Generating a Token

To authorize, use this code:

curl  --user "your_public_key:your_private_key" \
  -d "grant_type=client_credentials" \
  https://www.selfmgmt.com/api/v1/oauth/token

# Require the oauth2 gem
require 'oauth2'

CLIENT_KEY = 'CLIENT_KEY'
CLIENT_SECRET = 'CLIENT_SECRET'

# This method will be used in the subsequent examples to generate a token object.
# However, you do not need to regenerate a token for each request if you save the token to a variable.
def get_token
  client = OAuth2::Client.new(CLIENT_KEY, CLIENT_SECRET, site: 'https://www.selfmgmt.com/api/v1', token_url: '/api/v1/oauth/token')
  client.client_credentials.get_token

rescue OAuth2::Error => e
  # If the auth request fails, the error data will be in the errors key of the response hash:
  e.response.parsed['errors']
end

If successful, the following typical JSON object will be returned:

{
  "access_token": "f61cLMAODCPrxTZ0uOqwqPNAwNAe8OgIxQzlGRUQzU1OTY4Mjc5RkQxMEI5QkMyNEJERjc3QTczNw",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error messages are returned in a JSON array with a code, reason and detail. A typical message is:

{
  "errors":[
    {
     "code": 401,
     "reason": "unauthorized",
     "detail": "invalid_credentials"
     }
    ]
}

To create a token you must send an authorization header (basic authorization) using your public key and private keys within a POST request. The endpoint to reach is:

https://www.selfmgmt.com/api/v1/oauth/token

To use this token in any endpoint, add this authorization header to your requests:

Authorization:Bearer <token>

Endpoints

/echoString

curl https://www.selfmgmt.com/api/v1/echoString/Hello%20World!

token = get_token
response = token.get('echoString/Hello%20World')
response.parsed

The above command returns JSON structured like this:

{
  "result": "Hello World!"
}

Used to test that you are connected

e.g., https://www.selfmgmt.com/api/v1/echoString/Hello%20World!

This endpoint does not require authorization and only accepts the GET method.

/oauth/token

curl -H "Authorization:Bearer <token>" https://www.selfmgmt.com/api/v1/oauth/token

token = get_token
response = token.get('oauth/token')
response.parsed

The above command returns JSON structured like this:

{
  "access_token": "f61cLMAODCPrxTZ0uOqwqPNAwNAe8OgIxQzlGRUQzU1OTY4Mjc5RkQxMEI5QkMyNEJERjc3QTczNw",
  "token_type": "Bearer",
  "expires_in": 3554
}

Used to create tokens POST as well as retrieve information about tokens GET. See the section “Generating a Token” on how to create a token. Below is an example using curl to view a token (using the GET method).

/assessmentLink

curl -H "Authorization:Bearer <token>" https://www.selfmgmt.com/api/v1/assessmentLink/pops/eng

token = get_token
response = token.get('assessmentLink/pops/eng')
response.parsed

The above command returns JSON structured like this:

{
  "assessment": {
    "link": "https://www.selfmgmt.com/assess/lpro/eng/MinTz2S5hhdp8fjcyTMas9dnTk1NDhBFQQcc4sU5hll7X8kzfb",
    "id": "cc4sU5hll7XQO0PlQ72ZIwwcpVX8kzfb"
  }
}

Returns a link to complete an assessment. Both the assessment acronym and language are specified in the endpoint. See the Appendix for assessment acronymns and language codes.

Note: this will return a randomly generated 36 alpha numeric string that we provide for you. This is will be required to retrieve results (see the the assessmentResults endpoint).

e.g., "id": "D2lFYf45VVbXqdWARl4l4DgpizTumY28"

Pre-populating Form Data

We can pre-populate information on the assessments to avoid having the candidate re-enter information you have on file.

Fields	Description
firstname	The first name of the candidate
lastname	The last name of the candidate
address	The street address of the candidate
city	The city of the candidate
zipcode	The zip/postal code of the candidate
state	The state of the candidate
country	The country of the candidate
telephone	The telephone number of the candidate
email	The email address of the candidate

Simply append the name=value pair(s) onto the querystring of the assessment link you receive. For example:

<link>&firstname=Jane&lastname=Doe

/assessmentResults

curl -H "Authorization:Bearer <token>"  https://www.selfmgmt.com/api/v1/assessmentResults/pops/eng/idValue

token = get_token
response = token.get('assessmentResults/pops/eng/idValue')
response.parsed

The above command returns JSON structured like this:

{
  "assessmentResults": [{
    "id": "XQUXSLPSESDR",
    "testDate": "2017/10/26",
    "firstName": "Jane",
    "lastName": "Sample",
    "gender": "F",
    "address": "123 Main St.",
    "city": "Buffalo",
    "state": "New York",
    "zipcode": "22345",
    "phone": "555-1212",
    "email": "jsample@yahoo.com",
    "country": "USA",
    "reportLink": "https://www.selfmgmt.com/pac/reports/spro/XQUXSLPSESDR/m/eng"
  }]
}

Retrieves results from an assessment taken. You must pass the test type (e.g, POPS), the language (e.g., en), followed by the ID we generate for you passed to us in the /assessmentLink endpoint.

If you have a custom callback url, please contact us for further information on how we implement this for you.

Language Codes

Our assessments are available in many languages. Contact the Self Management Group for futher information on availabilty and language support.

Code	Language
eng	English
ara	Arabic
asm	Assamese
ben	Bengali
bul	Bulgarian
chi	Chinese (Simplified)
cht	Chinese (Traditional)
cze	Czech
dut	Dutch
est	Estonian
far	Farsi
fra	French (France)
fre	French
ger	German
grk	Greek
guj	Gujarati
hin	Hindi
hun	Hungarian
ind	Indonesian
ita	Italian
jap	Japanese
kan	Kannada
jhm	Khmer
kor	Korean
lit	Lithuanian
mal	Malay
mam	Malayalam
mar	Marathi
ori	Oriya
pol	Polish
ptb	Portuguese (Brazil)
pun	Punjabi
rom	Romanian
rus	Russian
slo	Slovak
spa	Spanish (Latin American)
sp2	Spanish (Spain)
tag	Tagalog
tai	Taiwanese
tam	Tamil
tel	Telugu
tha	Thai
tur	Turkish
ukr	Ukranian
vie	Vietnamese

Assessment Codes

Use the acronym in the endpoints where appropriate. We add new assessments on a per demand basis. Contact the Self Management Group for futher information on availabilty and language support.

Code	Assessment
lpro	LeaderPro
mpp3	ManagementPro 3.0
pops	POPScreen
pop6	Personal Orientation Profile 6.0
pop7	Personal Orientation Profile 7.0
spro	SalesPro

Error Messages

If you attempt to initiate a request that does not contain a supported verb for the endpoint, you will get a message as follows:

{
  "errors": [
   {
      "code": 405,
      "reason": "method_not_allowed",
      "detail": "allowed_methods: GET"
    }
  ]
}

All other errors should be self-explanatory as seen from the example below where an invalid token was sent to the endpoint:

{
  "errors": [
    {
      "code": 400,
      "reason": "bad_request",
      "detail": "invalid_token_error"
    }
  ]
}

All messages are returned in a JSON array with with the keyword errors being the top level node. Contents include an error code, a reason and a detail. The http status code is also returned in the http response.

Error Code	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
500	Internal Server Error – We had a problem with our server. Please try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.