Help Center > Section > Data Center

Help Center

Article - Encoura API Documentation

NOTE: we removed the Deliveries array from the /datacenter/exports response on July 1, 2024, to improve performance. See Frequently Asked Questions below for details.

Getting Started

Institutions can automate the import and export of recruitment data and admissions files using the Encoura Application Programming Interface (API). 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
     College name
     Service account email address

We recommend the service account email address be related to an alias or distribution list such as admissions@college.edu instead of a specific person, jdoe@college.edu. 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:

  1. Encoura API PDF - Document at the bottom of this page includes step-by-step instructions for importing and exporting data using the API
  2. Sample Scripts - Sample scripts available in GitHub to assist with your integration
  3. Swagger Documentation - Additional documentation available in open API format at https://developers.encoura.org

Frequently Asked Questions

Where do I find specifications and sample files for the exported files?
The file layout information and sample files are available in the related articles on ACT® College Score Report Files, the Encoura Standard Export Layout, and the Encoura Inquiry Layout.

Can I export Prospect files?
Yes, you can export any file that appears on the Export Files page in your Encoura Data Center. 
NEW: Yield+ model score files are available as of October 30, 2024, using the product key “model-scores.yield-plus”.

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.


My integration started failing recently. I no longer see the filename or other details in the Deliveries section of the response. What happened?
On July 1, 2024 we removed the Deliveries array from the response to the /datacenter/exports request, because it was causing performance issues.
Instead, we always instruct users to get the file UID from the top of the response. See the next item, "Where do I find the file UID....?".  For examples, see https://developers.encoura.org

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": "2a7k4x9b-dg73-25db-m620-334701957uEn", 

 "productKey": "score-reporter",

 "purchaseGroupUid": null,

 "sfFulfillmentId": null, 

 "purchaseItems": [],

 "status": "NotDelivered",

 . . . .

 

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 apiKey and a login. How can I get those?
If you have not yet received your service account email, OrganizationID, 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.

  1. Authenticate - Send a login request with your username (or service account email address), password, and apiKey 
    Receive a response with your session token and OrganizationID
  2. Get a list of files - Include the session token, apiKey, OrganizationID, and parameters (status, productKey)
    Receive a response with a list of available file UIDs that match the parameters
  3. Get a download URL - Include headers (session token, apiKey, OrganizationID) and a file UID
    Receive a download URL for a single file UID 
  4. Download the file - Not an API request; downloaded 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 article Encoura Standard Import Layout.

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.