Register as an API user: You will need to register as an API user in order before you can send request to an API instance, sandbox or local. For the sandbox instance, you register by filling out a short form on the landing page of the API, located at https://www.assessmentcenter.net/ac_api, and clicking the Request UserID/Password button. You will receive a response than contains your RegistrationOID and Token, which will be used for BASIC Authentication for each API requests.
Response Example
Registration Information
RegistrationOID 0BCAF1C4-XXXX-XXXX-XXXX-6F49FBB6CF98
Email michael-bass@northwestern.edu
Token 4186CDCF-XXXX-XXXX-XXXX-47B701FED108
JWT eydSZWdpc3Ry
You should also receive an email with a link to activate the account. Once you click the link, you will then be able to start using the API.
E-mail Example
Thank you for registering to use the Assessment Center IRT API.
Below is your registration information:
Registration ID: 0BCAF1C4-XXXX-XXXX-XXXX-6F49FBB6CF98
Token: 4186CDCF-XXXX-XXXX-XXXX-47B701FED108
Note: Registration ID and Token are needed for all API requests.
They are passed using BASIC Authentication.
To start using the API, navigate to the following url: to Activate your registration.
For local instances, you will not receive an e-mail unless you enable an SMTP server in the web.config file. In this case, update the dbo.registration as follows:
UPDATE dbo.Registration SET Status = 1 Where RegistrationOID = @RegistrationID
where @RegistrationID is specified in the email and response received during registration.
Request a list of available forms: Once you have activated your account, the next task you will want to do is list all the available forms. To do this, you will send a request to the Forms endpoint. Documentation for this endpoint is located at http://www.assessmentcenter.net/ac_api/2012-01/Docs/Forms . The format of the request is
{website}/{API app name}/{API version}/Forms/.{response format}.
So for the sandbox instance the request would be:
https://www.assessmentcenter.net/ac_api/2014-01/Forms/.{json|xml}
If you send the above request in a browser, you will be prompted for your User Name/Password credentials. Use your RegistrationOID and Token accordingly.
The response back from the server will be a list of forms below is a sample of the formatted truncated response:
Forms endpoint Response Example
{"Form":[
{"OID":"3BBD1D6B-","Name":"Neuro-QoL Banco Ped v1.0 Ansiedad"},
{"OID":"6D7441F7-","Name":"Neuro-QoL Banco Ped v1.0 Estigma"},
{"OID":"C1E44752-","Name":"PROMIS SF v1.0-Pain Interference 8a"}
. . .
]}
In order to return the details of a Form (i.e. all the items or questions), send a request as follows:
{website}/{API app name}/{API version}/Forms/{FormOID}.{response format}.
So a request to the sandbox instance of the PROMIS SF v1.0-Pain Interference 8a form, in json format would be:
https://www.assessmentcenter.net/ac_api/2014-01/Forms/C1E44752-BCBD-4130-A307-67F6758F3891.json
The response back from the server will be a json object that has the details for all the items of the specified form. A formatted truncated response for the above request is as following:
Form details Response Example
{"DateFinished":"",
"Items":[
{
"FormItemOID":"0E488C03-0EBC-429A-9E50-85E8D0E8012D",
"ID":"PAININ9",
"Order":"1",
"ItemType":"",
"Elements":[
{"ElementOID":"8AB8BA58-3BB0-40B6-B656-C24F1169069B",
"Description":"In the past 7 days",
"ElementOrder":"1"
}, ,
{"ElementOID":"B8630087-5995-4B62-8BE1-55BDEA27A80A",
"Description":"ContainerForB8630087-",
"ElementOrder":"3",
"Map":[
{"ElementOID":"949D2A4E-",
"Description":"Not at all",
"FormItemOID":"0E488C03-",
"ItemResponseOID":"66448F41-",
"Value":"1",
"Position":"1"},
]
]
},{ Remaining Items of the form}
]
}
This response is useful if you want to integrate the API with another system. You could load the metadata for forms into another system for reporting and linking API results. It is best to use the FormOID and item IDs attributes for linking values.
Register an assessment: Before you can have a participant start an assessment, you first need to request a unique token for that assessment. The token represents a single assessment administration of a specific form to a specific participant. The API endpoint for this request is Assessments and documentation for this endpoint is located at http://www.assessmentcenter.net/ac_api/2012-01/Docs/Assessment. The format of this request is
{website}/{API app name}/{API version}/Assessment/{Form OID}.{response format}.
So for the sandbox instance, the request to request an assessment token for the PROMIS SF v1.0-Pain Interference 8a form would be:
https://www.assessmentcenter.net/ac_api/2014-01/Assessments/ C1E44752-BCBD-4130-A307-67F6758F3891.json
The response back from the server will be a json object similar to the following:
Assessment Endpoint Response Example
{
"OID":"d16170e0-bb1c-4942-9eab-c43efc7f13bb"
,"UID":""
,"Expiration":"2/16/2017 12:36:53 PM"
}
In the above object the Assessment Token would be the OID (i.e. d16170e0-bb1c-4942-9eab-c43efc7f13bb). The Expiration date is a suggested time in which an assessment should be finished, by default it is 3 day after an assessment has been requested.
Administer an assessment to a participant: Once you have your assessment token, you can now administer the assessment to participants. The API endpoint for this request is Participants and documentation for this endpoint is located at http://www.assessmentcenter.net/ac_api/2012-01/Docs/Participant . The format of this request is
{website}/{API app name}/{API version}/Participants/{Assessment Token}.{response format}.
So for the sandbox instance to administer the PROMIS SF v1.0-Pain Interference 8a form to the participant assigned the above assessment token, the request would be:
https://www.assessmentcenter.net/ac_api/2014-01/Participants/d16170e0-bb1c-4942-9eab-c43efc7f13bb.json
The response will be an object containing one form item that will then need to be rendered to an UI so that the participant can respond to the item or question. All description attributes of Elements, bolded below, are displayed to participants. An annotated example of a returned item is below:
Participant Endpoint Response Example
{"DateFinished":"",
"Items":[
{"FormItemOID":"0E488C03-0EBC-429A-9E50-85E8D0E8012D",
"ID":"PAININ9",
"Order":"1",
"ItemType":"",
"Elements":[
//*** Elements that do not have a child Map collection represent question text and context
{"ElementOID":"8AB8BA58-3BB0-40B6-B656-C24F1169069B",
"Description":"In the past 7 days",
"ElementOrder":"1"},
{"ElementOID":"5B10732E-3A51-438C-A437-B07E2CFBE71A",
"Description":"How much did pain interfere with your day to day activities?",
"ElementOrder":"2"},
/*
Elements that contain a child Map collection represent response options for the participant to respond to. The Map collection contains elements in which the description attribute should be displayed to the participant.
*/
{"ElementOID":"B8630087-5995-4B62-8BE1-55BDEA27A80A",
"Description":"ContainerForB8630087-5995-4B62-8BE1-55BDEA27A80A","
ElementOrder":"3",
"Map":[
{"ElementOID":"949D2A4E-3A2B-4CD6-BE45-33C56EA76813","
Description":"Not at all",
"FormItemOID":"0E488C03-0EBC-429A-9E50-85E8D0E8012D",
"ItemResponseOID":"66448F41-20FC-4B6E-A810-740AA9BB76CA",
"Value":"1",
"Position":"1"},
{"ElementOID":"7C45E84C-87A5-410B-BF19-29D75531EFF4","Description":"A little bit","FormItemOID":"0E488C03-0EBC-429A-9E50-85E8D0E8012D","ItemResponseOID":"404DF429-41F2-4AED-AF36-4995C28BBFD9", "Value":"2","Position":"2"},
//A participant will endorse a response option by sending back the ItemResponseOID and Value attributes
{"ElementOID":"441EE176-E592-4B32-B5FE-83B738EB10BA",
"Description":"Somewhat",
"FormItemOID":"0E488C03-0EBC-429A-9E50-85E8D0E8012D",
"ItemResponseOID":"8E66D38C-7A34-4F05-B1D1-3224D1754A02",
"Value":"3",
"Position":"3"},
{"ElementOID":"29BD9E0E-298C-4A51-99C3-48B9D4D25B07","Description":"Quite a bit","FormItemOID":"0E488C03-0EBC-429A-9E50-85E8D0E8012D","ItemResponseOID":"48D33F53-327E-477C-A1AE-C1F130BE07B8", "Value":"4","Position":"4"},{"ElementOID":"74DC8842-078A-4DC6-B9C9-1656A8775657","Description":"Very much","FormItemOID":"0E488C03-0EBC-429A-9E50-85E8D0E8012D","ItemResponseOID":"EDDD1EE1-3712-4C33-822F-C85E2310DF36", "Value":"5","Position":"5"}]}]}]}
When the above object is displayed to the participant, they will answer the question by endorsing one of the Map objects by sending the ItemResponseOID and Value attributes back to the server on the same endpoint (i.e.
This request will return the next item. This process continues until the DateFinished attribute is not null which indicate the assessment is finished.
Finished Participant Endpoint Response Example
Your result will look like the following:
{"DateFinished":"2/13/2017 3:02:41 PM","Items":[]}
Returning the results of the Assessment: Once the assessment is finished, you can use the Assessment token to request the scored audit log of the entire assessment. The API endpoint for this request is Results and documentation for this endpoint is located at http://www.assessmentcenter.net/ac_api/2012-01/Docs/Score . The format of this request is
{website}/{API app name}/{API version}/Results/{Assessment Token}.{response format}.
So for the sandbox instance to return the scored audit trail for the PROMIS SF v1.0-Pain Interference 8a form administered using the above assessment token, the request would be:
https://www.assessmentcenter.net/ac_api/2014-01/Results/d16170e0-bb1c-4942-9eab-c43efc7f13bb.json
The response back from the server will be a json object similar to the following formatted truncated object. It represents the scored form along with the answered assessment items. Theta attribute represent the raw score and StdError represents the standard deviation of this score. The ItemResponseOID of the Item matches the selected Element ItemResponseOID. For this example the participant selects the response element with the text Not at all.
Results Endpoint Response Example
{ "UID":"",
"Name":"PROMIS SF v1.0-Pain Interference 8a",
"StdError":"0.153779107861919",
"Theta":"0.226543399619812",
"Status":"",
"Items":[
{
"FormItemOID":"51011021-53EF-496B-9AE1-875E12B21F01",
"ItemResponseOID":"6D64BAE7-B9C6-4ED0-A8B6-C417C21E954F",
"ID":"PAININ13",
"Position":"8",
"StdError":"",
"Theta":"",
"Response":"1",
"ItemType":"",
"Elements":[
{"ElementOID":"8AB8BA58-3BB0-40B6-B656-C24F1169069B",
"Description":"In the past 7 days",
"ElementOrder":"1"},
{"ElementOID":"AEE9D3C8-9D30-42B7-AB84-0C8F9CFE2501",
"Description":"How much did pain interfere with your family life?",
"ElementOrder":"2"},
{"ElementOID":"B8630087-5995-4B62-8BE1-55BDEA27A80A",
"Description":"ContainerForB8630087-5995-4B62-8BE1-55BDEA27A80A",
"ElementOrder":"3",
"Map":[
{"ElementOID":"949D2A4E-3A2B-4CD6-BE45-33C56EA76813",
"Description":"Not at all",
"FormItemOID":"51011021-53EF-496B-9AE1-875E12B21F01",
"ItemResponseOID":"6D64BAE7-B9C6-4ED0-A8B6-C417C21E954F",
"Value":"1",
"Position":"1"},
]}]}, { remaining answered items in the form}
]}]}