Getting Started
Institutions are able to automate the import and export of recruitment data and admissions files using the Encoura® API (Application Programming Interface). The API is accessible with proper authorization and credentials from Encoura Member Support & Services. If you have not received your service account email, Organization Id, and/or apiKey from Encoura, please submit a request. Once approved, you will be supplied with a service account, an OrganizationID, and an apiKey to interact with the API.
It is important to note that the Encoura API is intended for software developers to build integrations with campus systems. There are three key resources to assist in your development efforts:
- Encoura API PDF - This document, at the bottom of this page, includes step-by-step instructions for importing and exporting data using the API.
- Sample Scripts - Sample scripts are available in GitHub to assist with your integration.
- Swagger Documentation - Additional documentation is also available in openAPI format at https://developers.encoura.org.
Frequently Asked Questions
Where do I find specifications for the exported files?
The file layout information is available in the Encoura Help Center:
Can I get a sample file showing me what exported files will look like?
A sample file is available in the the Encoura Help Center:
Can I export Prospect files?
Yes, you can export any file that appears on the Export Files page in your Encoura Data Center.
For the Export function, the parameter shown is NotDelivered; are there other query parameters available?
Yes, you can also request previously-exported files using ‘Delivered’ for the status. Once you have it set up, the API is designed primarily to provide access to new files not yet exported. Files are marked as NotDelivered until they are returned in a list of available files.
Is there a way to use date parameters to limit the export files returned using the API?
While you can't use a date parameter, the API will, by design, only return files from the previous 30 days. You can use the “limit” and “skip” parameters to specify the number of files to include in the response. For example, “limit=1” will return only 1 file. If you have 3 results, “skip=2” will skip the first 2 files in the list and return the 3rd.
Where do I find the file UID in the list of files for Export?
The file UID is at the top of the response to the /datacenter/exports request:
[{
“uid”: “1e6c6d8e-af30-43ca-a519-395734701eba”, ← This is the file UID
“fice”: “SAMPLE”,
“organizationUid”: “1e6c6d8e-af30-43ca-a519-395734701eba”,
“productKey”: “score-reporter”,
“purchaseItems”: [],
. . . .
What is the best way to test the Export API while in development?
When you get your list of available files, the UID for each file can be saved and re-used to request a new download URL as many times as you need for testing purposes. You can also request previously-exported files using ‘Delivered’ for the status.
Why do I get an error when I try to log in?
Be sure you are including the required headers. See the attached documentation.
How can I access the API? What tools do I need?
You can use a variety of methods to access the API. You will need a REST API client, such as Postman, HTTPie, or the command line cURL, or you can create your own script or integration. A sample Python script is provided that you can adapt for your own needs. You can also try out the API at https://developers.encoura.org/.
I need the API Key and a login. How can I get those?
If you have not yet received your service account email, Organization Id, and/or apiKey from Encoura, please submit a request.
What is the process, from start to finish, for getting files?
Here are the steps to export files. For more detail, see the attached documentation.
- Authenticate. Send a login request with your username (or service account email address), password, and API key.
Receive a response with your session token and organization ID. - Get a list of files. Include the session token, API key, Organization ID, and parameters (status, productKey).
Receive a response with a list of available file UIDs that match the parameters. - Get a download URL. Include headers (session token, API key, Org ID) and a file UID.
Receive a download URL for a single file UID. - Download the file. This step is not an API request. The download URL is temporary and will expire after a short time.
Can I use the API to upload data files to Encoura?
Yes, the documentation below includes details on using the Encoura API to import or export files.
Where can I find the specifications for data uploaded through the API?
Data should be provided using the Encoura Standard Import specifications available in the Encoura Help Center.