Institutions can 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 Support.
PLEASE NOTE: The Encoura API is intended for software developers to build integrations with campus systems, requiring the use of developer tools to access the API.
1. Request an Encoura API service account
Proper authorization and credentials are required for accessing the Encoura API. Submit a request for a service account via the Encoura Help Center.
The information required for the request:
Contact name, email address and job title
Service account email address
We recommend the service account email address be related to an alias or distribution list such as email@example.com instead of a specific person, firstname.lastname@example.org. Once approved, you will be supplied with a service account, an OrganizationID, and an apiKey to interact with the API.
2. Activate your Encoura API service account
The service account information is delivered via email to the contact email address included in the request. The email outlines instructions for activating the Encoura API service account and includes the credentials to interact with the API.
3. Coordinate with your software developer support
It is important to note that the Encoura API is intended for software developers to build integrations with campus systems. Coordinate with your software developer support for building the interface to upload and download data files. There are three key resources to assist in 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
. . . .
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 exporting ACT or Encoura 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.
What if the file I'm uploading has different field names than the Encoura Standard Import?
When using the API to automate your file upload, you should first go to Data Center and use the File Upload tab to manually upload your file. This will prompt you to map any fields that don't match the Encoura Standard Layout. Once you do this, your mappings are saved and automated uploads will work going forward. If you ever make changes to your uploaded file layout, remember to repeat this process.