Export API User Guide

The SlideRoom Export API provides HTTP endpoints to automate the export of data from the SlideRoom system. Generally, the Export API provides features and options that match those available to users in the SlideRoom web interface when exporting applications. These include the ability to export tabular data in delimited formats such as .CSV, as well as .PDF files of the applications and .ZIP file downloads of application materials. 

This guide will walk you through the process of setting up exports from SlideRoom into your local database using the API. Note that the SlideRoom Advanced Plan includes developer support, so if you are on that plan tier, feel free to reach out to our Client Support team for additional assistance with setting up API exports. Further technical specifications are also available in the SlideRoom API Documentation

 



Goals of this guide

checkmark.png  Generate an API Token

checkmark.png  Understand how the API works

checkmark.png  Request an export

checkmark.png  Get export results

checkmark.png  Appendix A: Export options

checkmark.png  Appendix B: Export filename templates

checkmark.png  Appendix C: Samples


 

 




Generate an API Token

  1. Required: Request an API Token.

    To do so, click on the gear icon in the top-right corner of your administrator dashboard, then select Account Settings. Click on Developer API in the menu on the left side of the page. There, you will see the option to generate an OAuth token. Click Generate API Token:

Screen Shot 2016-11-10 at 9.53.56 AM.png

 

 

2. Optional: Download the SlideRoom API Client in your language of choice.

SlideRoom API client libraries are available in both C# and Java in our SDK documentation. These are not required to interact with the API, but may be used to simplify development.

 

 




Understand how the API works

Asynchronous Exports

As with exporting data via the SlideRoom web interface, API-based exports are asynchronous operations. This means that first a request to generate an export is made via the API, then additional requests are made to the API to check on the status of, and ultimately download, the export file(s). As larger SlideRoom exports sometimes take minutes to complete, developers should allow ample delay before checking on the status of an export via the API. Generally, an appropriate check interval would be one minute between each status check.

The overall process to generate and download an export from SlideRoom is as follows:

Untitled.png

 

Delivery

As an alternative to the status/download cycle in the API, you may configure an export delivery location in the SlideRoom web interface. This delivery location can include Dropbox, Google Drive, Box.com, or an SFTP server. Once configured, the delivery location can be passed as an option when requesting an export, and the file(s) will be delivered to that location when completed. This approach is particularly well-suited for systems that already have an automated process to import data from a known location.

 

 




Request an export

To initiate the process of an application data export in SlideRoom, you must first request the export from the “application” resource of the API. This request can be made for a single application or a batch of applications.

 

Exporting a Single Application

HTTP

POST /api/v2/application/{applicationId}/request-export HTTP/1.1
Host: api.slideroom.com
Authorization: Bearer {API-KEY}

 

C#

var client = new SlideRoomClientV2("API-KEY");

var applicationId = "0123456789";
var exportParms = new RequestExportByApplicationIdV2Parameters() { … };

var exportResponse = await client.Application.RequestExportByApplicationIdV2Async(applicationId, exportParms, CancellationToken.None);

 

Java

SlideRoomClientV2 client = new SlideRoomClientV2("API-KEY");

String applicationId = "123";

SlideRoomClientV2.Models.Application.RequestExportByApplicationIdV2Parameters params = new SlideRoomClientV2.Models.Application.RequestExportByApplicationIdV2Parameters();

// params.[property] = ...;

SlideRoomClientV2.Models.RequestApplicationExportResultV2 result = client.Application.RequestExportByApplicationIdV2(applicationId, params);

 

Exporting Multiple Applications in a Batch

HTTP

POST /api/v2/application/request-export HTTP/1.1
Host: api.slideroom.com
Authorization: Bearer {API-KEY}

 

C#

var client = new SlideRoomClientV2("API-KEY");
var exportParms = new RequestExportV2Parameters() { … };
 

var exportResponse = await client.Application.RequestExportV2Async(exportParms, CancellationToken.None);

 

Java

SlideRoomClientV2 client = new SlideRoomClientV2("API-KEY");

SlideRoomClientV2.Models.Application.RequestExportV2Parameters params = new SlideRoomClientV2.Models.Application.RequestExportV2Parameters();

// params.[property] = ...;

SlideRoomClientV2.Models.RequestApplicationExportResultV2 result = client.Application.RequestExportV2(params);

 

Response

Once the export request is accepted, the API will return a structure containing an export token. The export token can be used to make subsequent calls to the API to get the results of the export. Additionally, the result structure contains the number of submissions to be included in the export as well as a message which may indicate any issues that would prevent the export from successfully generating.

HTTP

{
   "token": number,
   "message": string,
   "submissions": number
}

 

C#

public class RequestApplicationExportResultV2
{
   public string message;
   public int submissions;
   public int token;
}

 

Java

public class RequestApplicationExportResultV2
{
   public String message;
   public Integer submissions;
   public Integer token;
}

 

 


 

Get export results

To get the results of an export request, you will issue a call to the “export” resource of the SlideRoom API. The export “token” returned from the initial export should be sent to the API call.

 

HTTP

GET /api/v2/export/{token} HTTP/1.1
Host: api.slideroom.com
Authorization: Bearer {API-KEY}

 

C#

var client = new SlideRoomClientV2("API-KEY");
var token = 123;
var exportResult = await client.Export.GetV2Async(token, CancellationToken.None);

 

Java

SlideRoomClientV2 client = new SlideRoomClientV2("key");

Integer token = 123;

SlideRoomClientV2.Models.ExportResultV2 result = client.Export.GetV2(token);


 

Response

The response structure for the export status endpoint contains a status string and a list of URLs from which the export files can be downloaded (if the original export request did not specify external delivery options). These URLs are private and expire within one hour of issuance.  Subsequent calls to this same endpoint may be made to get fresh URLs.

 

The possible values for the status field include:  “Pending”, “Complete”, and “Delivered”

 

HTTP

{
   "status": string,
   "total_files": number,
   "completed_files": number,
   "file_urls": Array
}

 

C#

public class ExportResultV2
{
   public string status;
   public int total_files;
   public int completed_files;
   public string[] file_urls;
}

 

Java

public static class ExportResultV2
{
   public String status;
   public Integer total_files;
   public Integer completed_files;
   public String[] file_urls;
}

 


 

Appendix A: Export options

When using direct HTTP requests to the API, options are sent as query string parameters. For example:

 

HTTP

POST /api/v2/application/request-export?format=csv HTTP/1.1

 

When using SDK clients, the export options are passed as part of the RequestExportParameters structure. For example:

 

C#

var exportParms = new RequestExportV2Parameters() {
   format = RequestExportV2Parameters.FormatEnum.csv
};

 

Java

SlideRoomClientV2.Models.Application.RequestExportV2Parameters params = new SlideRoomClientV2.Models.Application.RequestExportV2Parameters();

params.format = SlideRoomClientV2.Models.Application.RequestExportV2Parameters.FormatEnum.csv;

 

Batch Application Export Options

The following options are available when requesting a batch export.

 

Parameter

Options

Notes

email

<user email address>

Optional.  The email address of a SlideRoom user by which the export should be “scoped”.  This will limit the applications in the export to that which the user is permitted to see.

searchName

<saved view name>

Optional.  This limits applications in the export to those found in a saved view (configured in the SlideRoom web interface)

since

<utc seconds since 1/1/1970>

Optional.  This limits the applications in the export to those submitted on or after the provided date.

status

all, inProgress, submitted

 

Optional.  This limits the applications in the export to those that have the given status.

pool

all, current, archived, commonAppSDS

Optional.  This limits the applications in the export to those from the given pool.

batchFilename

<template>

Optional.  Batch files (.zip) and folders will be named using the provided template.  See Appendix A for template options.

 

Delivery Options

The following options allow the export to be delivered outside of SlideRoom.

 

Parameter

Options

Notes

delivery.account

<account name>

Optional.  Delivers the export to the account defined in the Integrations section of the SlideRoom web interface.

delivery.folder

<subfolder name>

Optional.

 

Tabular/Spreadsheet Export Options

The following options are available when exporting tabular/spreadsheet data.

 

Parameter

Options

Notes

format

csv, txt, tab, xlsx

Required.

tab.export

<custom export name>

Required.  This is the name of a custom export schema defined in the Export Builder section of the SlideRoom web interface.

roundType

current, assigned, named

Optional.

roundName

<round name>

Optional.  Only used when roundType is “Named”

 

PDF Export Options

The following options are available when exporting applications as PDF files.

 

Parameter

Options

Notes

format

pdf

Required

pdf.includeComments

true, false

Optional

pdf.includeCommonApp

true, false

Optional

pdf.includeForms

true, false

Optional

pdf.includeHighlights

true, false

Optional

pdf.includeMedia

true, false

Optional

pdf.includeFullPageMedia

true, false

Optional

pdf.includeApplicantAttachments

true, false

Optional

pdf.includeOrganizationAttachments

true, false

Optional

pdf.includeRatings

true, false

Optional

pdf.includeReferences

true, false

Optional

roundType

current, assigned, named, all

Optional.

roundName

<round name>

Optional.  Only used when roundType is “Named”

 

ZIP Export Options

The following options are available when exporting application files.

 

Parameter

Options

Notes

format

zip

Required

zip.includeComments

true, false

Optional

zip.includeCommonApp

true, false

Optional

zip.includeForms

true, false

Optional

zip.includeMedia

true, false

Optional

zip.includeOriginalMedia

true, false

Optional

zip.includeApplicantAttachments

true, false

Optional

zip.includeOrganizationAttachments

true, false

Optional

zip.includeRatings

true, false

Optional

zip.includeReferences

true, false

Optional

roundType

current, assigned, named, all

Optional.

roundName

<round name>

Optional.  Only used when roundType is “Named”

 

 



Appendix B: Export filename templates

Export filenames may be customized by specifying the filename and batchFilename options when requesting an export. Additionally, these options support template variables that allow the insertion of data from the application into the filename.  To include a template variable in the filename, surround the variable name with braces as follows: 

 

?filename={DATE} - Application {APPLICATION_ID} - {FULL_NAME}

 

Note: For batch files, template variables that reference specific application data will only resolve if the value is consistent across all of the individual applications within the batch.

 

Available Variables

 

Name

Notes

DATE

The date of the export formatted as YYYY-MM-DD

YEAR

The year component of the export date

MONTH

The month component of the export date

DAY_OF_MONTH

The day component of the export date

TOTAL_APPLICATION_COUNT

The total number of applications in the export batch request.  When an export is split into multiple batch files, this number will be greater than the number of files within any of the batch files.

EXPORT_NAME

Supported only when requesting a tabular/spreadsheet export.  This is the name of the custom export schema used for the export.

APPLICATION_ID

The full application ID.

COMMONAPP_ID

The Common App ID associated with the applicant for the common app season of the application.

FULL_NAME

The fully resolved name of the applicant formatted as {last},{first} or {app org},{last},{first}, when appropriate.

FIRST_NAME

The applicant’s first name.

LAST_NAME

The applicant’s last name.

APPLICANT_ORG_NAME

The applicant’s organization, when specified.

PROGRAM_NAME

The program in which the application was submitted.

PROGRAM_ID

The unique ID for the program in which the application was submitted.

FILE_NUMBER

When an export is split into multiple batch files, a unique index number (1..n) will be assigned to each batch file.

FILE_APPLICATION_COUNT

For a batch file, the number of applications within the file.

RANGE_START

For batch exports, the export-level index of the first application within the batch file.

RANGE_END

For batch exports, the export-level index of the last application within the batch file.

 




Appendix C: Samples

Exporting tabular data in .CSV format using the C# SDK.

The following sample console application requests a .CSV export of all current applications that have been submitted in the last 7 days, using a custom export schema defined in the SlideRoom web interface.

Prerequisites:

  • API Token
  • Define a custom export schema in the SlideRoom web interface

 

using SlideRoom.SDK;
using SlideRoom.SDK.Model.Application;
using System;
using System.IO;
using System.Net;
using System.Threading;
using System.Threading.Tasks;

namespace Sample
{
   internal class Program
   {
       private static void Main(string[] args)
       {
           MainAsync(args).Wait();
       }
 

       private static async Task MainAsync(string[] args)
       {
           var apiKey = "MY-API-KEY";
           var exportName = "My Custom Export";
           var since = DateTime.Now.AddDays(-7);
 

           var client = new SlideRoomClientV2(apiKey);

           // request the export
           var response = await client.Application.RequestExportV2Async(new RequestExportV2Parameters
           {
               format = RequestExportV2Parameters.FormatEnum.csv,
               since = ToUTCSeconds(since),
               tab = new RequestExportV2Parameters.TabParameters
               {
                   export = exportName
               }
           }, CancellationToken.None);
 

           var exportToken = response.token;
 

           //
           while (true)
           {
               // wait 1 minute before checking on export
               Thread.Sleep(60 * 1000);
 

               // request export status
               var checkResponse = await client.Export.GetV2Async(exportToken, CancellationToken.None);
 

               Console.WriteLine("Status: " + checkResponse.status);
 

               // report details when export export complete
               if (checkResponse.status == "Complete")
               {
                   Console.WriteLine("{0}/{1} file(s) complete:",
                       checkResponse.completed_files,

                       checkResponse.total_files
                   );
 

                   using (var webClient = new WebClient())
                   {
                       foreach (var url in checkResponse.file_urls)
                       {
                           var uri = new Uri(url);
                           var fileName = Path.GetFileName(uri.AbsolutePath);
 

                           Console.WriteLine("Downloading {0}", url);
                           webClient.DownloadFile(uri, fileName);
                       }
                   }
                   break;
               }
           }
 

           Console.WriteLine("Done");
       }
 

       private static int ToUTCSeconds(DateTime dateTime)
       {
           var utcZero = new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
           var timeSpan = dateTime.ToUniversalTime() - utcZero;
           return (int)timeSpan.TotalSeconds;
       }
   }
}

 


 

Additional Resources

We hope this helps get you started, but there are plenty of additional resources available for you. These include: 

  1. SlideRoom API Documentation
  2. SlideRoom Client Support
  3. SlideRoom Integration with Salesforce
  4. SlideRoom Integration with Slate
  5. SlideRoom Integration with Zapier
  6. SlideRoom Integration with MailChimp

Want a copy of this guide as a PDF so you can take it anywhere? Download it here.