Quickstart
Index
Connect to the DecidED API
The first thing you need to do is to sign up a new user. Visit the API App and register with a new user, or log in with your existing DecidED user if you already use our Advisor or Student apps. You need to join an existing organization or create one for yourself.
Registration to the DecidED API currently involves getting in touch with our team while the system is being developed.
Once you have your user set up, you can explore the API by using the graphical interface itself. You can also explore the actual API by using the GraphQL explorer that's embedded in the application, or you can directly query the API through its endpoint. The embedded GraphQL explorer will be useful for navigating through the available operations and queries, and reading the documentation for each one.
If you're interested in querying the API directly you will need an API key, which you can create from your profile. Then you will have to authenticate each request by sending the Authorization: Bearer <YOUR_KEY> header.
Upload a Financial Aid Award Letter to extract its data
Now that you have set up your user and API key, you can follow the examples right from the embedded GraphQL explorer or by sending raw HTTP requests with cURL or any other HTTP client of your choice. Keep in mind that the GraphQL explorer acts on your production data.
To process a letter or batch of letters we need to create a "Job". A job is nothing more than container for one or multiple letters that need to be processed. Creating and processing a job consists of 2 steps:
- Create the Job object and indicate the file names of the letters you will upload.
- For each file, you will receive a signed URL to upload the letters to our storage solution. Each letter is uploaded and processed independently, so you can upload them in any order.
After the letters are uploaded, you can monitor the progress of each letter by either polling the API or setting up webhooks. At any point you can request a CSV export of your job, even if it hasn't finished processing yet.
Example
We will be using cURL to follow this example, but any tool capable of doing HTTP requests will work.
We want to create a job to process one letter. First of all we will query the id of our organization. As a DecidED API user, you belong to one or more organizations so you will need to specify in which one you are performing your operations.
echo '
query {
me {
organizations {
id
}
}
}
' \
| tr -d '\n' \
| sed 's/"/\\"/g' \
| xargs -0 -I % curl https://api.decided.org/api/graphql/ \
-H 'authorization: Bearer <YOUR_KEY>' \
-H 'content-type: application/json' \
--data-raw '{"query": "%", "variables": null}'
Which will return us something like:
{
"data": {
"me": {
"organizations": [
{
"id": "<ORG_ID>"
}
]
}
}
}
So now we know <ORG_ID> is the id of our organization. With this information, we invoke the createJob mutation with the file name of our only letter.
echo '
mutation {
createJob(
organizationId: <ORG_ID>,
letterFiles: [{filename: "letter1.jpg"}],
name: "Tutorial Job",
) {
job {
id
}
awardLetters {
uploadUrl
}
}
}
' \
| tr -d '\n' \
| sed 's/"/\\"/g' \
| xargs -0 -I % curl https://api.decided.org/api/graphql/ \
-H 'authorization: Bearer <YOUR_KEY>' \
-H 'content-type: application/json' \
--data-raw '{"query": "%", "variables": null}'
And we receive a signed URL to upload our letter to the DecidED letter storage, along with our job's id which we will use later.
{
"data": {
"createJob": {
"job": {
"id": "<JOB_ID>"
},
"awardLetters": [
{
"uploadUrl": "<SIGNED_URL>"
}
]
}
}
}
To upload your letter, execute a PUT request to the <SIGNED_URL> with the Content-Type: application/octet-stream header and the raw body of your image.
curl -X PUT -H 'Content-Type: application/octet-stream' \
--data-binary '@./path/to/letter1.jpg' '<SIGNED_URL>'
When the upload finishes, it will trigger the classification process for that letter. We can use the job id returned in the job creation to query how our letter is doing. We want it to be in the READY status.
echo '
query {
jobs(organizationId: <ORG_ID>, filter: {jobId: "<JOB_ID>"}) {
items {
awardLetters {
items {
id
status
aidAmounts {
description
value
category
subCategory
source
}
costAmounts {
description
value
categories {
category
}
}
}
}
}
}
}
' \
| tr -d '\n' \
| sed 's/"/\\"/g' \
| xargs -0 -I % curl https://api.decided.org/api/graphql/ \
-H 'authorization: Bearer <YOUR_KEY>' \
-H 'content-type: application/json' \
--data-raw '{"query": "%", "variables": null}'
You may get the PENDING status at first while it is processing, but eventually you will receive a response with the READY status if everything went right. Other statuses represent different, non successful situations that we may encounter while processing your letter; like it exceeding our size limit or our system not being able to extract data from it.
When the letter is READY, we can also drill into the aid and cost data extracted from it.
{
"data": {
"jobs": {
"items": [
{
"awardLetters": {
"items": [
{
"id": "8",
"status": "READY",
"aidAmounts": [
{
"description": "Federal Pell Grant",
"value": 3445,
"category": "GRANT",
"subCategory": "PELL",
"source": "FEDERAL",
},
{
"description": "Federal Direct Subsidized Loan",
"value": 3500,
"category": "LOAN",
"subCategory": "SUBSIDIZED",
"source": "FEDERAL",
},
{
"description": "Est. Federal Parent PLUS Loan",
"value": 26500,
"category": "LOAN",
"subCategory": "PARENT_LOANS",
"source": "FEDERAL",
}
],
"costAmounts": [
{
"description": "Tuition",
"value": 8040,
"categories": [
{
"category": "TUITION"
}
]
}
]
}
]
}
}
]
}
}
}
Finally, let's request a CSV export of our job. The file will be generated asynchronously and it'll be sent to the email address of our user.
echo '
mutation {
exportJob(organizationId: <ORG_ID>, jobIdList: ["<JOB_ID>"]) {
ok
}
}
' \
| tr -d '\n' \
| sed 's/"/\\"/g' \
| xargs -0 -I % curl https://api.decided.org/api/graphql/ \
-H 'authorization: Bearer <YOUR_KEY>' \
-H 'content-type: application/json' \
--data-raw '{"query": "%", "variables": null}'
And that's it! You have learned to connect to our API and process letters.