The Letter Processing Service

What is the Letter Processing Service

The Letter Processing Service is an online system that can process Financial Aid Award Letters and automatically extract aid and cost data from them. Letters that can't be entirely processed by our automatic classifiers can optionally be manually reviewed by one of our team members to extract the data. In both cases, the data is extracted in the same format and it can be queried directly over the API, exported to CSV, and communicated in real time over webhooks.

The service can be used both from the API or from the API App.

Jobs

The process starts by creating a job, which is a collection of letters which will be processed together. File names cannot be duplicate between letters of the same job.

A job can contain any number of letters. If you plan to integrate this service in your own system to process letters uploaded by users in real time, you can create jobs with just one letter.

Letter files limitations

We currently support the following formats for our letters:

• jpeg
• jpg
• png
• pdf
• heic
• zip

We recognize formats based on the extension of the file name, so it's important that files have the correct one. JPEG is commonly used with two different extensions (jpeg and jpg) which is why we support both of them.

The zip format is used for multipart letters.

Files can have a maximum size of 5.0MB. Some formats need conversion before processing (like zip files). In these cases, we check the file size after it is converted, so it is possible to get a size-related error even if the original file is under the limit.

Multipart letters

If you upload a zip file with multiple images in it, it will be processed as a multipart letter. These are useful to process letters that consist of several screenshots of a website that won't fit in a single screenshot, which we've found to be a common practice among smartphone users.

The images will be "stitched" together, in the order resulting from ordering them by name, while trying to eliminate duplicate sections of the letter, and it will be processed as a single file.

The zip file should not contain subdirectories or other files that are not images.

Letter statuses

Once they are uploaded, letters will go through different statuses that indicate at which step of the process they are, or what is the result of it. The possible values are:

• PENDING: The letter has not been uploaded or is still processing.
• MANUAL_REVIEW: We couldn't process the letter automatically and it's waiting a manual review from our team.
• READY: The letter has been processed correctly.
• INVALID: The file was manually reviewed and we determined this is not a valid award letter.
• NOT_SUPPORTED: We couldn't process the letter automatically, although we might have extracted some partial data. However, manual review was not enabled for this Job so we couldn't complete the process.
• BAD_FILE: We don't support this type of image, the file is not an image, or the file is damaged.
• CANCELED: The Job was canceled before we could process this letter.
• SIZE_LIMIT_EXCEEDED: The file (after conversion) is bigger than our limit of 5MB.
• RESULTS_PURGED: The file was processed successfully but the results were purged

Passing context data to letters

In the case of uploading many letters to our service you may find the need to attach some contextual data to each letter. If the letter was uploaded by a user of your own system, you could attach the id of such user.

We provide a text field for this use case, called payload, that can hold arbitrary data for each letter. We don't use this data, but you can query it back after the letter has been processed to better understand or process the results.

In the specific case of wanting to attach the IPEDS id of the college which submitted the letter, we provide a separate school field for this purpose. We may use this data in the future, and we are planning to give rewards to users who complete this field.