A request with the GET verb returns the JSON-encoded reference value for this applicant. Note that the value appear to be a double-quoted value, but is a JSON string literal in the strict sense. If there is no reference value, null is returned.
A reference value can be anything, usually it is the applicant's ID or code in another related system, for example the applicant's student ID in the Study Information System (SIS).
GET /api/applicants/123/reference Host: apply.example.edu Authorization: DREAM apikey="..."
Content-Type: application/json Content-Length: 123
200 OK | The reference value is returned |
"ABC123"
When making a PUT call, the contents of the request body will be stored as the new reference value for the applicant in question.
The body must be a JSON encoded string literal, this means that it has to be double-quoted like “ABC123”, not just ABC123. A minimum of 3 and a maximum 16 characters are allowed and the reference value can only contain uppercase letters, numbers, dots, dashes and slashes.
Note that the reference code also needs to be unique. An error is returned if this code has already been assigned to another applicant.
Example curl:
curl -v -X PUT --data '"ABC123"' -H "Authorization: DREAM apikey=\"YOUR_API_KEY\"" https://your-da-instance.dreamapply.com/api/applicants/123/reference
PUT /api/applicants/123/reference Host: apply.example.edu Authorization: DREAM apikey="..."
Content-Type: text/plain Content-Length: 0
204 No Content | The reference value was stored successfully |
400 Bad Request | This reference is already assigned to another applicant, or another error - see the returned text for details |