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.

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.

After obtaining the Secure Token via an API call, the partner site will then need to redirect the user to the Magnus Health Portal and include the token in the redirect request.

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 to the demo sandbox.

Information for your production configuration can be found within the Admin Dashboard.

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.

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).
Note: The update functionality of this method has been deprecated – please use the updateUser method instead

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 preferredName
The nickname or the preferred name of the user.

String middleName
The middle 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 [Deprecated] Please use the updateUser method to update users
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”}

This method is used for updating demographic information in an existing student or parent account. Account Token is used as criteria for determining which user will have the update applied. If you do not know the desired account token value, it can be obtained by first calling the createUser endpoint with fields provided for only vendor key, registration code, and nonce.
Do not call this method on administrative accounts (such as school or corporate accounts).

Note on method parameters:

• Nonce and accountToken are required fields, all other parameters are optional.
• Excluding a field or sending a null value for it will preserve its existing value.
• Setting a field as empty string will clear existing data – with the exception that Students cannot have the date of birth cleared once set.

String firstName: The first name of the user.

String middleName: The middle name of the user.

String preferredName: The nickname or the preferred name of the user.

String lastName: The last name of the user.

String homePhoneNumber: The home phone number of the user.
user

String workPhoneNumber: The work phone number of the user.

String cellPhoneNumber: The cell phone number of the user.

String email: The email address of the user.

String dateOfBirth: A static format string to be used as the date of birth of the user. The date format should be in “mm/dd/yyyy”.

String sex: The biological sex of the user.

String addressLineOne: The street address of the user.

String addressLineTwo: The apartment, suite, or space number of the user.

String addressCity: The city of the user.

String addressState: The state or province of the user.

String addressZipCode: The zip code of the user.

String addressCountry: The country of the user..

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

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.

Example JSON Sent:
{“firstName”:”Albertus”, “middleName”:”Orange”, “preferredName”:”Albert”, ”lastName”:”Magnus”,”homePhone”:”919-599-2917”, “cellPhone”:””, ”email”:”albert.magnus@magnushealthportal.com”, ”dateOfBirth”: “10/14/2006”, “addressLineOne”:”323 W Martin St”,”addressCity”:”Raleigh”,”addressState”:”NC”,”addressZipCode”:”27601″,”addressCountry”:”United States”,”accountToken”: “MPh0vm2rva53Bv1pbdzz1Q”, ”nonce”:”267445405250”}”

Example Responses:

Success
{“secureToken”:”c1bbstU0kZE5vTJnIxjhK”,”accountToken”:”MPh0vm2rva53Bv1pbdzz1Q”,”username”:”amagnus”,”message”:”Successfully updated account”}

Failure
Error: Invalid Account Token

NOTE: specific error message text may vary based on failure reason

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

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

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

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

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

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

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

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

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

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

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

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