Documents

API version
Select a version to change the base URI
in syntax and code examples. Learn about versions
:

Represents a list of documents attached to the application.

URI
/api/v9/applications/ID/documents

GET List documents

Get a list of documents that have been attached to this application. The HEAD verb is useful if you only want to test if this application has any documents attached at all (and how many). Use the GET verb to get the listing of documents.

In order to retrieve the binary data of the document, you need to use GET /api/v9/applications/ID/documents/ID.

Syntax
GET /api/v9/applications/123/documents
Host: apply.example.edu
Authorization: DREAM apikey="..."

Example request

Request
curl
curl \
  -X GET \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v9/applications/123/documents"

Response headers

HeaderValueDescription
Content-Typeapplication/jsonMedia type of the resource
Content-Length1234Size of the response body in bytes
X-Count15Number of documents attached to this application

Response codes

Response codeDescription
200 OKThe list of documents was successfully returned

Example response

Response
{
  "222": {
    "id": 222,
    "uploaded": "2014-04-29T15:46:38+00:00",
    "name": "Passport",
    "mime": "image/jpeg",
    "size": "1966954"
  },
  "333": {
    "id": 333,
    "uploaded": "2014-04-29T15:46:38+00:00",
    "name": "Diploma",
    "mime": "image/jpeg",
    "size": "310178"
  }
}

POST Upload a document to the application

Initiate an upload process to add a new document to the application.

You can also upload a document to a specific task. For details, see POST /api/v9/applications/ID/tasks/ID/documents.

Syntax
POST /api/v9/applications/123/documents
Host: apply.example.edu
Authorization: DREAM apikey="..."

The process is as follows:

  1. Client calls POST /api/v9/applications/123/documents:

    Request
    curl
    curl \
   -X POST \
   -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
   "https://apply.example.edu/api/v9/applications/123/documents" \
   -v

  2. API returns code 204 and an ingress URL on the Location header, such as https://svcs-ingress.dreamapply.com/........ that contains a JWT token, authorising the upload.

  3. Client pushes a file using a standard multipart request, for example:

    Request
    curl
    curl \
   -X POST \
   -F 'upload=@/path/to/your/image.jpg' \
   "https://svcs-ingress.dreamapply.com/temp-upload-token"

  4. The ingress service returns code 201 if the file was accepted.

The ingress URL is valid for 30 minutes to upload the file (or files - the URL can be used multiple times to upload multiple files within the 30 minute window). Up to 10MiB are allowed, and any of the usual MIME-s are allowed (same as in the UI).

Example request

Request
curl
# --- Configuration variables ---
API_KEY="YOUR-API-KEY"
APP_ID="APPLICATION-ID"
DOCUMENT_PATH="PATH-TO-DOCUMENT.JPG"
BASE_URL="https://apply.example.edu"

# 1. Initiate upload and extract ingress URL
INGRESS_URL=$(curl -X POST \
    -H "Authorization: DREAM apikey=\"$API_KEY\"" \
    "$BASE_URL/api/v9/applications/$APP_ID/documents" \
    --silent --head \
    | perl -n -e 'print $1 if /location:\s*(\S+)/i' \
    | tr -d '\r\n' \
)

# Check if the URL was successfully retrieved
if [ -z "$INGRESS_URL" ]; then
    echo "CRITICAL ERROR: Failed to retrieve Ingress URL (Token)."
    echo "Double-check your API Key, Application ID, and Task ID."
    exit 1
fi

echo "Successfully retrieved Ingress URL."

# 2. Execute Upload using the extracted URL
echo "Starting file upload of '$DOCUMENT_PATH' to Ingress Service..."

curl -X POST \
    -F "upload=@$DOCUMENT_PATH" \
    "$INGRESS_URL" \
    -w "\nUpload HTTP Status: %{http_code}\n"

Response codes

Response codeDescription
204 No ContentThe ingress URL was returned in the Location header

Previous

Exports

Next

ZIP archive