API Overview and Documentation

In order to get access to our Single Sign On services and API you will need to request access. Once you’re approved you will be assigned a Client ID that will uniquely identify your partner site within our system.

Please login to view more information

Magnus Health’s API implements a two-phase security system that ensures that user identifiable information is never sent across an insecure medium unencrypted. All calls within the API follow the same consistent pattern.

Please login to view more information

After obtaining the Secure Token via an API call, the partner site will then need to redirect the user to the following URLs:

Please login to view

A unique Secure Token link is generated after every call to the API. This link will be live for a configurable period of time. The system default is ten minutes. After this time period, the Secure Token expires.

Our current test setup is to use our “demo” system which will contain your test client ID and encryption key. Simply change your URL to point at:

Please login to view

Our current production setup uses the URL:

Please login to view

SSO – (Single Sign On)

JSON – (JavaScript Object Notation)

Tracker– is the default segmentation for users. This is usually the class graduating or enrolling years.

Secure Token – a token that is assigned via an API call that will allow a user to seamlessly login to the site. This token is good for a pre-configured period of time after it is assigned. The default is 10 minutes. This token is 32 alphanumeric case sensitive characters.

If the user was not assigned an account token in the past, due to the fact that they were an organic sign up, your call to CreateUser will generate a new account token for that user and return it.

JSON parameters:

String username: suggested username, if this username is not available and the vendorKey does not exist in the system this call will create a user with a username = username+’x’ where x is the next available digit.

String vendorKey: a unique identifier for this user in your partner system, it must be passed along in every API call, and if this number does not match any found in the system then a new user will be created.

String firstName : the first name of the user.

String lastName: the last name of the user.

String phone: the phone number of the user.

String email: the email address of the user.

[Deprecated] Long dateOfBirth: a long representing the date of birth of the user (use CDT)

String dateOfBirthString: a static format string to be used as the date of birth instead of dateOfBirth, if dateOfBirthString is specified, then Long dateOfBirth is ignored. The date format should be in “mm/dd/yyyy”.

Long expirationDate: the date that this membership should expire, typically a year from the current date. If no expirationDate value is passed the system default for that customer will be used.

String registrationCode: the package code to be used in generating the new account

String nonce: a random value that is assigned for this particular call. We recommend but do not require that this be the current timestamp in a long. DO NOT REPEAT THIS VALUE. This value is used to stop replay/split header injection attacks. If a nonce value is repeated then the system will simply return an error code.

Return:

Secure Token: used to perform SSO. This secure token may only be used once to login after that it is deactivated.

Account Token: String unique value that represents a user on the Magnus Health site.

Username: String the unique value that the API picked for your user’s username.

JSON Sent:

{“username”:”amagnus”, “vendorKey”: “Azy834Itlw0”, “firstName”:”Albert”, ”lastName”:”Magnus”,”phone”:”919-599-2917”, ”email”:”albert.magnus@magnushealthportal.com”, ”dateOfBirth”: 259445405250, ”registrationCode”:”MHP123456”, ”nonce”:”267445405250”}

Returns:

{“secureToken”:” ea5FqaS0eZnoty62XYVmSUej0frTX0UP”, “accountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “username”:“amagnus”}

JSON Parameters:

String accountToken: the account token that was passed back from the CreateUser method.

String vendorKey: the partner’s unique vendor key that is used to double check the values.

String nonce: unique value that is passed along to every API call that prevents replay attacks.

Returns:

String secureToken: a unique string that will allow the user access to the site

JSON Sent:

{“accountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “vendorKey”:”Azy834Itlw0”, “nonce”:”267446780000”}

Returns:

{“secureToken”:”ea5FqaS0eZnoty62XYVmSUej0frTX0UP”}

JSON Parameters:

String accountToken: the account token that was passed back from the CreateUser method.

String vendorKey: the partner’s unique vendor key that is used to double check the values.

String nonce: unique value that is passed along to every API call that prevents replay attacks.

String trackerName: the name of the tracker you are trying to set the user on. This needs to be an exact match to the tracker name in the Magnus Health secure website.

String code: the registration code (package code) that the user is on

Returns:

boolean setSuccessfully: true if the tracker was set without errors

JSON Sent:

{“accountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “vendorKey”:”Azy834Itlw0”, “nonce”:”267446780000”, “code”:”AB12MH”, “trackerName”:”Class of 2012″}

Returns:

{“setSuccessfully”:”true”}

JSON Parameters:

String accountToken: the account token that was passed back from the CreateUser method.

String vendorKey: the partner’s unique vendor key that is used to double check the values.

String code: the registration code (package code) that the user is on

String status: either “archive” or “active” the status that you want to change the specified user to

String nonce: unique value that is passed along to every API call that prevents replay attacks.

Returns:

String status: “active” if the user is active in the system or “archive” if the user has been archived.

JSON Sent:

{“accountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “vendorKey”:”Azy834Itlw0”, “code”:”AB12MH”, “status”:”active”,“nonce”:”267445550000”}

Returns:

{“status”:”success”}

JSON Parameters:

String accountToken: the account token that was passed back from the CreateUser method.

String vendorKey: the partner’s unique vendor key that is used to double check the values.

String code: the registration code (package code) that the user is on

String nonce: unique value that is passed along to every API call that prevents replay attacks.

Returns:

String status: “active” if the user is active in the system or “archive” if the user has been archived.

JSON Sent:

{“accountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “vendorKey”:”Azy834Itlw0”, “nonce”:”267445550000”, “code”:”AB12MH”}

Returns:

{“status”:”active”}

JSON Parameters:

String code: the registration code (package code) that you would like to query

String nonce: unique value that is passed along to every API call that prevents replay attacks.

Returns:

An array of rows, one row per data owner:

String vendorkey: vendor defined identifier

Integer numComplete: number of items completed.

Integer numItems: number of items total to complete.

Boolean complete: true if all requirements are complete and everything is reviewed, false otherwise.

String trackerName: the name of the tracker (e.g. Graduating Class of 2013)

Boolean userComplete: true if the student has filled out all requirements, false otherwise.

JSON Sent:

{“code”:”AB12MH”, “nonce”:”266445505390”}

Returns:

{“packageDetails”:[{“vendorKey”:”78222000”,”numComplete”:6,”numItems”:8, “complete”:false, “trackerName”:”Class of 2012”, “userComplete”: false}, {“vendorKey”:”78222100”,”numComplete”:8,”numItems”:8, “complete”:true, “trackerName”:”Class of 2014”, “userComplete”: false},
{“vendorKey”:”78222003”,”numComplete”:0,”numItems”:0, “complete”:false, “trackerName”:”None Selected”, “userComplete”: false} ] }

JSON Parameters:

String code: the registration code (package code) that you would like to query

String nonce: unique value that is passed along to every API call that prevents replay attacks.

Long deltaStartDate: a long representing the date to start looking for the delta of users who have had their status change. This could be they have newly answered requirements, changed answers, or something was reviewed. (use CDT)

Returns:

An array of rows, one row per data owner:

String vendorkey: vendor defined identifier

Integer numComplete: number of items completed.

Integer numItems: number of items total to complete.

Boolean complete: true if all requirements are complete and everything is reviewed, false otherwise.

String trackerName: the name of the tracker (e.g. Graduating Class of 2013)

Boolean userComplete: true if the student has filled out all requirements, false otherwise.

JSON Sent:

{“code”:”AB12MH”, “nonce”:”266445505390”, “deltaStartDate”: 1319498044338 }

Returns:

{“packageDetails”:[{“vendorKey”:”78222000”,”numComplete”:6,”numItems”:8, “complete”:false, “trackerName”:”Class of 2012”, “userComplete”: false}, {“vendorKey”:”78222100”,”numComplete”:8,”numItems”:8, “complete”:true, “trackerName”:”Class of 2014”, “userComplete”: true}, {“vendorKey”:”78222003”,”numComplete”:0,”numItems”:0, “complete”:false, “trackerName”:”None Selected”, “userComplete”: false} ] }

This method returns detailed information about a given user on a specific package.

JSON Parameters

String accountToken: an encrypted form of the account token

Example account Token: MPh0vm2rva53Bv1pbdzz1Q

String vendorKey: an encrypted form of the partner’s vendor key which is used to double check

String code: the registration code (package code), eg “AB12MH” or “MHP1234gtvde89”, that you would like to query on

String nonce: unique value that is passed along to every API call that prevents replay attacks.

Returns:

The tracker’s name, the tracker’s due date, and a list of items that the data owner has required for that tracker. If the user has not selected a tracker yet, then this call will return a trackerNamed “None Selected” and all other fields will be blank.

An Array of Items:

String itemStatus: an enumeration of five possible values (approved, rejected, expired, pending, incomplete).

String itemName: the name of the item
Long nextActionDate: date representing the next action that’s required by the system. A zero if there is no nextAction date (eg the item is complete). (in CDT)

Long administeredDate: date representing the administered date that was captured from the reviewer in the system

Long lastModifiedDate: date representing the last time the answer was edited. Usually this is the student fulfilling the requirement or the reviewer reviewing it.

String recordType: string representing the record type as specified by the reviewer.

String trackerName: the name of the tracker that this user belongs to, or an empty string if they have not selected a tracker yet.

Long dueDate: a long representing a date that this tracker is due

Boolean complete: if the student is complete and fully reviewed

Integer numComplete: number of requirements the student has completed

Integer numItems: total number of requirements for the student to fill out

JSON Sent:

{“accountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “vendorKey”:”Azy834Itlw0”, “code”:”AB12MH”, “nonce”:”267446780000”}

Returns:

{“trackerName”:”Magnus University”,”dueDate”:259445405250, “numComplete”: 1, “numItems”: 2, “complete”, false, “Items”:[{“itemName”:”2011 Physical”,”itemStatus”:”pending”,”nextActionDate”: 259446655250, “administeredDate”: 259406655250, “lastModifiedDate”: 259426655250, “recordType”: “”},{“itemName”:”Hep B”,”itemStatus”:”expired”,”nextActionDate”: 259446655250, “administeredDate”: 259406655250, “lastModifiedDate”: 259426655250, “recordType”: “”} } }