Seamless Integrations with Magnus Data Services

Seamless student portal integration with Application Programming Interface

Get a Demo

Our powerful Application Programming Interface (API) facilitates interaction between your school’s information system and Magnus Health to create and update student and parent account information.

Magnus Health’s robust application programming interface (API) facilitates interaction between your school’s information system and Magnus Health. Schools that are already using a student information system can take advantage of having a single sign-on (SSO) integration with Magnus Health’s web-based SMR (student medical record).

This integration saves time for school administrators and parents by bringing their student health records online and reporting back to the school when certain pieces of information are missing. Additionally, Magnus Health has developed several reporting functions that allow your system to pull raw and aggregate data back from the Magnus Health system.
The API requires a minimal amount of data on your users to set up this integration. Simply provide the first name, last name, phone number, email address, date of birth, and customer ID or vendor key (unique student identifier from your student information system) and the API authenticates those users into their Magnus Health account. No additional usernames, passwords, or URLs are needed. SSO reduces password fatigue among users and decreases the amount of password-related phone calls to your IT department. Users also feel more secure that they are being directed to the portal directly from the school’s website.

Magnus Health exposes several reporting functions via the API. The first function returns aggregated information about the total number of students complete and for those incomplete, their progress at that time. The other function identifies, for a given student, their current status in the system, if they’ve completed all their requirements, and their progress toward completing those requirements.

API Resources

API Account Setup

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

APIAuthentication

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

Secure Token Link

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 more information

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.

Single Sign On Test Environment

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 more information

Production Environment

Our current production setup uses the URL:

Please login to view more information

Glossary
API – Application Programmer Interface

SSO – Single Sign-On

JSON – JavaScript Object Notation

Tracker – The default segmentation for users. This is usually the graduating class or enrollment term.

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.

Methods

JSON parses based on commas, apostrophes, and semicolons, make sure to escape all input with a back-slash before sending.

CreateUser METHOD

The “user” call is the one-stop shop for the SSO API. Create User will perform one of two operations. The call will either provision the user, if the specified vendor key has never been provided before, and will return a new Secure Token to enable SSO, or if the vendor key has been used before and matches up against an existing user in our system, then the information provided will be ignored and the call will simply return a new Secure Token. Do not call this method on administrative accounts (such as school or corporate accounts).

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.

Long dateOfBirth [Deprecated]
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 update
If this is set to “true” then the API will update new fields for this user. The username and vendorKey parameters will never be updated.

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.

Returns

String secureToken
Used to perform SSO. This secure token may only be used once to login after that it is deactivated.

String accountToken
Unique value that represents a user on the Magnus Health site.

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

Example 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”}"

Example Return

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

SecureToken METHOD

This method will return a Secure Token given the vendor key for a user. You may call this method on any user within Magnus Health that is associated with your reseller account. Please note that a Secure Token may only be used once and will timeout ten minutes after it is issued by default.

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

Example JSON Sent

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

Example Return

{“secureToken”:”ea5FqaS0eZnoty62XYVmSUej0frTX0UP”}

SetTracker METHOD

After the API has been used to successfully create a user, you have the ability to set the tracker for that user. If the user logs into Magnus Health before this is set, they will be prompted to select their tracker. This method will return a simple boolean to state whether the call succeeded.

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

Boolean overrideArchive (Optional)
Whether or not to override the users current membership if they are archived or not. Defaults to false.

Returns

Boolean setSuccessfully
true if the tracker was set without errors

Example JSON Sent

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

Example Return

{“setSuccessfully”:”true”}

setMembershipStatus METHOD

This call allows Magnus Health integration partners to change the membership status for users in their account. In practice this allows partners to automatically archive (“remove”) users from counts and reports when the user has been removed from the partner’s system. This is often used after users have graduated or have withdrawn. If this call is a duplicate, meaning that your request should “archive” an individual who is already archived, the system will simply return success and make no changes.

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.

Example JSON Sent

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

Example Return

{“status”:”success”}

getMembershipStatus METHOD

This call will return back the status of the given user, if the user is archived or active. If a user is archived, they will receive no email updates and may not be permitted to login to the Magnus Health system.

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.

Example JSON Sent

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

Example Return

{“status”:”active”}

getPackageCounts METHOD

This method returns a listing of users that are on the given account package/registration code. This call doesn’t return users that were on this package code but have been archived off.

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.

Example JSON Sent

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

Example Return

{“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} ] }

PackageCountsSince METHOD

Returns a listing of users that are on the given account package code whose account status has changed since the given delta date. This call doesn’t return users that were on this package code but were archived off.

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.

Example JSON Sent

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

Example Return

{“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} ] }

getUser METHOD

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 accountToken: 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

Example JSON Sent

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

Example Return

{“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”: “”} } }

parentUser METHOD

The “parentUser” call is the one-stop shop for the SSO API for Parents. This method will perform one of two operations. The call will either provision the parent, if the specified vendor key has never been provided before, and will return a new Secure Token to enable SSO, or if the vendor key has been used before and matches up against an existing user in our system, then the information provided will be ignored and the call will simply return a new Secure Token. Do not call this method on administrative accounts (such as school or corporate accounts).

If the parent was not assigned an account token in the past, due to the fact that they were an organic sign up, your call to “parentUser” 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 parent 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 parent.

String lastName
The last name of the parent.

String phone
The home phone number of the parent. (Optional)

String cellPhone
The cell phone number of the parent. (Optional)

String workPhone
The work phone number of the parent. (Optional)

String email
The email address of the parent.

String address
The street address of the parent. (Optional)

String city
The city of the parent. (Optional)

String state
The state of the parent. (Optional)

String zip
The zip code of the parent. (Optional)

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 update
If this is set to “true” then the API will update new fields for this parent. The username and vendorKey parameters will never be updated.

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.

Returns

String secureToken
Used to perform SSO. This secure token may only be used once to login after that it is deactivated.

String accountToken
Unique value that represents a user on the Magnus Health site.

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

Example JSON Sent

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

Example Return

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

childUser METHOD

This method is to be used by schools that have parents logging into Magnus to action items on behalf of their children, who are students at the school. The “childUser” call should be used to provision the student before joining any parents to them. When this method is called, if the specified vendor key has never been provided before, the student will be created. If the vendor key has been used before and matches up against an existing user in our system, then the information provided will be ignored and the call will simply return a new Secure Token, to be used for SSO if the student ever needs to login for themselves in the future. Do not call this method on administrative accounts (such as school or corporate accounts), or for schools that do not use the parent – child relationship.

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 student(child) 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 child.

String lastName
The last name of the child.

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”.

String phone
The home phone number of the child. (Optional)

String cellPhone
The cell phone number of the child. (Optional)

String workPhone
The work phone number of the child. (Optional)

String email
The email address of the child. (Optional)

String address
The street address of the child. (Optional)

String city
The city of the child. (Optional)

String state
The state of the child. (Optional)

String zip
The zip code of the child. (Optional)

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 update
If this is set to “true” then the API will update new fields for this child. The username and vendorKey parameters will never be updated.

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.

Returns

String secureToken
Used to perform SSO. This secure token may only be used once to login after that it is deactivated.

String accountToken
Unique value that represents a user on the Magnus Health site.

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

Example JSON Sent

{“username”:”amagnus”, “vendorKey”: “Azy834Itlw0”, “firstName”:”Albert”, ”lastName”:”Magnus”,”dateOfBirthString”: '09/12/2000", ”registrationCode”:”MHP123456”, ”nonce”:”267445405250”}

Example Return

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

parentChildRelationship METHOD

This method is used to create relationships between parents and students after both have been created in the school’s account. This method verifys that all information is correct, as well as that the child is a student in our system and the parent is a parent in our system. This will return a status “success” if everything was setup correctly, and an error code if there were any issue.

JSON parameters

String parentVendorKey
A unique identifier for this parent in your partner system, it was used to create the parent

String parentAccountToken
A identifier passed back from Magnus when the parent was created

String childVendorKey
A unique identifier for this student(child) in your partner system, it was used to create the student

String childAccountToken
A identifier passed back from Magnus when the student(child) was created

String code
The registration code (package code) that the parent and child are on

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.

Returns

String status
“success” if the call completed successfully or “error” followed by a description of the error

Example JSON Sent

{“parentVendorKey”:”Azy834Itlw0”, “parentAccountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “childVendorKey”:”Azy834Itlw0”, “childAccountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, ”code”:”MHP123456”, ”nonce”:”267445405250”}

Example Return

{“status”:”success”}

removeParentChildRelationship METHOD

This method is used to remove relationships between parents and students. This method verifys that all information is correct, as well as that the child is a student in our system and the parent is a parent in our system. This will return a status “success” if everything was removed correctly, and an error code if there were any issue.

JSON parameters

String parentVendorKey
A unique identifier for this parent in your partner system, it was used to create the parent

String parentAccountToken
A identifier passed back from Magnus when the parent was created

String childVendorKey
A unique identifier for this student(child) in your partner system, it was used to create the student

String childAccountToken
A identifier passed back from Magnus when the student(child) was created

String code
The registration code (package code) that the parent and child are on

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.

Returns

String status
“success” if the call completed successfully or “error” followed by a description of the error

Example JSON Sent

{“parentVendorKey”:”Azy834Itlw0”, “parentAccountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, “childVendorKey”:”Azy834Itlw0”, “childAccountToken”:”MPh0vm2rva53Bv1pbdzz1Q”, ”code”:”MHP123456”, ”nonce”:”267445405250”}

Example JSON Sent

{“status”:”success”}

logout METHOD

This method is used to for logout of a user. This should only be used if you are sure they are no longer active.

JSON parameters

String VendorKey
A unique identifier for this user in your partner system, it was used to create the user

String AccountToken
A identifier passed back from Magnus when the account was created

Returns

String status
“Success – Session removed for user” if the call completed successfully or “error” followed by a description of the error

Example JSON Sent

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

Example JSON Sent

{“result”:”“Success – Session removed for user”}

Connect Your System

Get a Demo