Reference code

Represents the reference code of an applicant.

/api/v10/applicants/ID/reference

GET Get a reference code

Retrieve the reference code of an applicant as a JSON-encoded string. The value is enclosed in double quotes and formatted as a JSON string literal. If no reference code is defined, the request returns null.

The reference code is an external identifier associated with the applicant. Common examples include the applicant ID, code or student ID from an external system, such as a Study Information System (SIS).

GET /api/v10/applicants/123/reference
Host: apply.example.edu
Authorization: DREAM apikey="..."

Example request

curl \
  -X GET \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v10/applicants/123/reference"

Response headers

Response codes

Example response

"ABC123"

PUT Set a reference code

Update the applicant’s reference code with the value provided in the request body.

The request body must contain a JSON-encoded string literal that meets the following requirements:

• The value must be enclosed in double quotes, for example, "ABC123", not ABC123.
• The allowed length is 3 to 16 characters.
• Allowed characters include uppercase letters (A-Z), numbers (0-9), periods (.), hyphens (-) and forward slashes (/).
• The reference code must be unique. If the specified code is already assigned to another applicant, the request returns the 400 Bad Request error.

PUT /api/v10/applicants/123/reference
Host: apply.example.edu
Authorization: DREAM apikey="..."

Example request

curl \
  -X PUT \
  -d '"ABC123"' \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v10/applicants/123/reference"

Response headers

Response codes