Export/Report Files (initiate a run)

Stability: production

Initiate the background execution of a specific export (e.g. export template). Required parameters are the identity that the export belongs to, and the id of the export that you wish to run. This will create an instance of a running export_file, which is what you can monitor to determine when the export is ready to be downloaded. The id in the response from this call is the handle to that running export_file and what is used in future calls to check on the status of the run.

Important note: this id representing the handle to the running instance of the export is not always uniquely generated with each run – if you attempt to run the same export several times in close succession, you will receive back the id of the already-running instance of that export. This is a safeguard to prevent many accidental simultaneous runs of the exact same export – one must finish before a new one can be initiated.

Attributes

Name	Type	Description	Example
export_files/export_id	integer	Unique identifier of the associated export.	86446
export_files/href	string	Hypertext reference to this resource. pattern: /api/v1/exports/\d+/export_files/\d+	"/api/v1/exports/86466/export_files/74780"
export_files/id	integer	Unique identifier of this export file.	74780
export_files/status	string	Current status of this export file. one of:"Initializing" or "Queued" or "In Progress" or "Available" or "Success With Errors" or "Empty List" or "Failed"	"Available"
href	string	Hypertext reference to this resource. pattern: /api/v1/user_identities/\d+/export_files	"/api/v1/user_identities/37442/export_files"

Export/Report Files (initiate a run)

Initiate the background execution of a specific export.

POST /api/v1/user_identities/:user_identity_id/exports/:export_id/export_files

Optional Parameters

Name	Type	Description	Example
callback	uri	For requests using the optional “callback” parameter, you should build your request as follows: /api/v1/user_identities/:user_identity_id/exports/:export_id/ export_files?callback=http://someurl.com/your_callback.cgi When the file is ready, WebAdMIT will POST to the callback URL that you specify with the following form POST parameters: export_file[id] export_file[export_id] export_file[status] An example of the body of a POST to a callback when a file is ready is as follows: export_file[id]=99752&export_file[export_id]=123316&export_file[status]=Available This gives you the export_file_id of the file that’s ready for download once it is available (you will use the export_id and the export_file_id POSTed here to form the next API call in item 5 below to actually get the URL to download the now-ready file). We recommend the use of the public RequestBin (http://requestb.in/) service in order to test out how this particular call works.	"http://someurl.com/your_callback.cgi"

Curl Example

$ curl -n -X POST https://api.webadmit.org/api/v1/user_identities/:user_identity_id/exports/:export_id/export_files \
  -d '{
  "callback": "http://someurl.com/your_callback.cgi"
}' \
  -H "Content-Type: application/json" \
  -H "x-api-key: 0123456789abcdef0123456789abcdef"

Response Example

HTTP/1.1 201 Created

{
  "export_files": {
    "id": 74780,
    "href": "/api/v1/exports/86466/export_files/74780",
    "export_id": 86446,
    "status": "Available"
  }
}

Not Found

Specific error messages

When the user_identity is not found

{
  "message": "User identity '999' not found."
}

When the program is not found

{
  "message": "Program '99999999999' not found."
}

When the applicant is not found

{
  "message": "Applicant '99999999999' not found."
}

When the custom field is not found

{
  "message": "CustomeField '99999999999' not found."
}

While these error messages are most often associated with resources that don't exist when making a GET request, please note that the same messages are also the response during POST, PUT, and PATCH requests if any resources specified by parameters cannot be found.

Generic error message (legacy error)

HTTP/1.1 404 Not Found

{
  "message": "Not Found"
}

Liaison is currently phasing out this error message in favor of more descriptive messages. If you encounter this message, please contact your Liaison representative with a detail description of the API request you made and one of our engineers will update the API.

Unauthorized

Response Example

HTTP/1.1 401 Unauthorized

(Empty response body.)

---