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 an application.

URI
/api/v10/applications/ID/documents

GET List documents

List all documents attached to an application.

To retrieve the document binary data, you can use GET /api/v10/applications/ID/documents/ID.

Syntax
GET /api/v10/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/v10/applications/123/documents"

Response headers

HeaderValueDescription
Content-Typeapplication/jsonThe media type of the resource
Content-Length1234The size of the response body in bytes
X-Count15The number of documents attached to the 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 an application.

You can also upload a document to a specific task. To do this, use POST /api/v10/applications/ID/tasks/ID/documents.

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

The process is as follows:

  1. The client calls POST /api/v10/applications/123/documents:

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

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

  3. The 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 one or more 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/v10/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

See Also

Previous

Courses

Next

ZIP archive