Back

FAQ

What are the API references for implementing the web service?

Below are the API references for implementing the PAScoresDwnld API. We also provide code samples to get you started.

Login and File Download API

PAScoresDwnld – Login
METHOD
POST
REQUEST
https://scoresdownload.collegeboard.org/pascoredwnld/login
DESCRIPTION
Login by username and password. This endpoint allows the user to get an access token that can be used in subsequent "/file" and "/files/list" endpoint calls with the token.
PAYLOAD (sample)
Content-Type: application/json
{"username": "exampleuser",
"password": "examplepass"}
RESPONSE (sample)
Accept: application/json
{"token":"45B5B7E7-1C85-DBE7-2493-DB6ECA41A707"}

PAScoresDwnld – Pre-signed URL by Filename and token
METHOD
POST
REQUEST
https://scoresdownload.collegeboard.org/pascoredwnld/file?filename={filename}
DESCRIPTION
Retrieve pre-signed AWS S3 URL by filename and access token (returned from login)
PAYLOAD (sample)
{"token":"45B5B7E7-1C85-DBE7-2493-DB6ECA41A707"}
RESPONSE (sample)
Accept: application/json
{"fileUrl":"https://kmscbtest.s3.amazonaws.com/K12/00000020150717000005.csv?AWSAccessKeyId=AKIAJBDJQ3DEKEFUYOOA&Expires=1433525962&Signature=01CV0qGNGQqQ93FERYXVehyWQfU%3D", 
"filePath":"00000020150717000005.csv"}

PAScoresDwnld – Pre-signed URL by Filename and Username/Password
METHOD
POST
REQUEST
https://scoresdownload.collegeboard.org/pascoredwnld/file?filename={filename}
DESCRIPTION
This is a convenient method to retrieve pre-signed AWS S3 URL by filename and username/password (do not need login first). The username and password are to be passed in a request payload in json format (similar to login endpoint).
PAYLOAD (sample)
Content-Type: application/json
{"username": "exampleuser",
"password": "examplepass"}
RESPONSE (sample)
Accept: application/json
{"fileUrl":"https://kmscbtest.s3.amazonaws.com/K12/00000020150717000005.csv?AWSAccessKeyId=AKIAJBDJQ3DEKEFUYOOA&Expires=1433525962&Signature=01CV0qGNGQqQ93FERYXVehyWQfU%3D", 
"filePath":"00000020150717000005.csv"}

File Directory Listing API

Request RESPONSE Data Key
Element Description
"fileType" Identifies the file type as Scores File or Other.
"assessment" Identifies the assessment as one of these: 
  • SAT
  • PSAT/NMSQT
  • PSAT 10
  • PSAT 8/9
Can be “N/A” for certain file types.
"adminDate" The month and year of the test administration where applicable. Can be “N/A” for certain file types.
"deliveryMethod" Identifies the file as one of these:
  • Score Release
  • Post Score Release 
  • One Time
Can be "N/A" for certain file types.
"deliveryDate" The date the file was posted.
"fileName" The name of the file. Used to request a pre-signed URL.
"batchId" The Batch Identifier for the Run that posted the file. This can be used when contacting customer service if you encounter any issues. Can be “N/A” for certain file types.
"recordCount" Numeric value identifying the total number of records in the file.
"fileSize" The size of the file in bytes. 
PAScoresDwnld – Full File Directory Listing of all files posted using Authentication Token
METHOD
POST
REQUEST
https://scoresdownload.collegeboard.org/pascoredwnld/files/list
DESCRIPTION
Retrieve data on all the files posted for your organization using the access token returned from login.
PAYLOAD (sample)
{"token":"45B5B7E7-1C85-DBE7-2493-DB6ECA41A707"}
RESPONSE (sample)
{
    "files": [
        {
            "fileType": "Scores File",
            "assessment": "SAT",
            "adminDate": "June 2016",
            "deliveryMethod": "Post Score Release",
            "deliveryDate": "2016-09-01",
            "fileName": "1234_20160901_000030.txt",
            "batchId": "123456_30",
            "recordCount": 50,
            "fileSize": 15853
        },
(repeats for each file)
    ]
}
NOTES:
1. For this request, the http headers – ACCEPT and CONTENT-TYPE needs to be set with application/json as values.
2. When no files have been posted, the RESPONSE will contain"files": null

PAScoresDwnld – Full File Directory Listing of all files posted using User Name/Password
METHOD
POST
REQUEST
https://scoresdownload.collegeboard.org/pascoredwnld/files/list
DESCRIPTION
Retrieve data on all the files posted for your organization using the user credentials (User Name/Password).
PAYLOAD (sample)
Content-Type: application/json
{"username": "exampleuser",
"password": "examplepass"}
RESPONSE (sample)
{
    "files": [
        {
            "fileType": "Scores File",
            "assessment": "SAT",
            "adminDate": "June 2016",
            "deliveryMethod": "Post Score Release",
            "deliveryDate": "2016-09-01",
            "fileName": "1234_20160901_000030.txt",
            "batchId": "123456_30",
            "recordCount": 50,
            "fileSize": 15853
        },
(repeats for each file)
    ]
}
NOTES:
1. For this request, the http headers – ACCEPT and CONTENT-TYPE needs to be set with application/json as values.
2. When no files have been posted, the RESPONSE will contain"files": null

PAScoresDwnld – File Directory Listing of all files posted since “fromDate” using Authentication Token
METHOD
POST
REQUEST
https://scoresdownload.collegeboard.org/pascoredwnld/files/list?fromDate={fromDate}
DESCRIPTION
Retrieve data on all the files posted for your organization since a date and time you provide using the access token returned from login.
PAYLOAD (sample)
{"token":"45B5B7E7-1C85-DBE7-2493-DB6ECA41A707"}
RESPONSE (sample)
{
    "files": [
        {
            "fileType": "Scores File",
            "assessment": "SAT",
            "adminDate": "June 2016",
            "deliveryMethod": "Post Score Release",
            "deliveryDate": "2016-09-01",
            "fileName": "1234_20160901_000030.txt",
            "batchId": "123456_30",
            "recordCount": 50,
            "fileSize": 15853
        },
(repeats for each file)
    ]
}
NOTES:
1. For this request, the http headers – ACCEPT and CONTENT-TYPE needs to be set with application/json as values.
2. {fromDate} follows standard ISO 8601 Date/Time syntax as follows:  yyyy-MM-dd'T'HH:mm:ssZ where “Z” indicates the time zone offset from UDT/GMT.  Example:  2016-01-30T23:11:55-0500 would be used for New York, NY EST.
3. File data for files posted AFTER the {fromDate} will be returned.
4. If an incorrect {fromDate} syntax is used, the RESPONSE will be:
	"message": "Invalid fromDate(yyyy-MM-dd'T'HH:mm:ssZ) value provided: {fromDate}"
5. When no files have been posted since {fromDate}, the RESPONSE will contain"files": null

PAScoresDwnld – Full File Directory Listing of all files posted since “fromDate” using User Name/Password
METHOD
POST
REQUEST
https://scoresdownload.collegeboard.org/pascoredwnld/files/list?fromDate={fromDate}
DESCRIPTION
Retrieve data on all the files posted for your organization since a date and time you provide using the user credentials (User Name/Password).
PAYLOAD (sample)
Content-Type: application/json
{"username": "exampleuser",
"password": "examplepass"}
RESPONSE (sample)
{
    "files": [
        {
            "fileType": "Scores File",
            "assessment": "SAT",
            "adminDate": "June 2016",
            "deliveryMethod": "Post Score Release",
            "deliveryDate": "2016-09-01",
            "fileName": "1234_20160901_000030.txt",
            "batchId": "123456_30",
            "recordCount": 50,
            "fileSize": 15853
        },
(repeats for each file)
    ]
}
NOTES:
1. For this request, the http headers – ACCEPT and CONTENT-TYPE needs to be set with application/json as values.
2. {fromDate} follows standard ISO 8601 Date/Time syntax as follows:  yyyy-MM-dd'T'HH:mm:ssZ where “Z” indicates the time zone offset from UDT/GMT.  Examples:  2016-01-30T23:11:55-0500 would be used for New York, NY EST and 2016-01-30T23:11:55+0100 would be used for Paris, FR CET.  +0000 should be used to indicate UDT/GMT.
3. File data for files posted AFTER the {fromDate} will be returned in RESPONSE.
4. If an incorrect {fromDate} syntax is used, the RESPONSE will be:
	"message": "Invalid fromDate(yyyy-MM-dd'T'HH:mm:ssZ) value provided: {fromDate}"
5. When no files have been posted since {fromDate}, the RESPONSE will contain"files": null