Applicants

Represents a list of applicants or leads registered in DreamApply.

/api/v9/applicants

GET List applicants

List applicants using the filters set as parameters. The number of applicants is represented in the X-Count header.

There is a hard limit of 32768 items returned, which is capped to 8192 if the expand parameter is used.

GET /api/v9/applicants
Host: apply.example.edu
Authorization: DREAM apikey="..."

Parameters

Notes

• Note [1]: Lists can be either comma or space separated. All list items are combined with logical OR operators — in other words an application is considered matching if it matches to any of the values in the list.
• Note [2]: you may use either tracker IDs or codes to reference trackers. However IDs are guaranteed not to change while the tracker codes offer no such guarantee.
• Note [3]: Some elements in the returned objects are links to other API requests. Using the expand parameter, it is possible to expand this data to the actual records, saving additional API requests. The full list of possible expansions is trackers,documents,consents,invoices,wishes. You can set one or multiple expansions, combining them in a comma-separated fashion to the expand parameter. Note also that using this parameter caps to limit to 8192 due to performance reasons.
• Note [4]: An ISO 8601 compatible datetime (inclusive) or the applicant ID to start from (inclusive). The date is applied to the registration time of the applicant, so you can only fetch applicants registered in the last N days, weeks or months. The applicant IDs are sequential integers, so you can simply save the last applicant ID you processed, and issue the next request with bySince=$lastID+1.

Example request

curl \
  -X GET \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v9/applicants?bySince=2025-10-01T00:00:00Z&byCitizenships=US,GB&expand=consents&limit=5"

Response headers

Response codes

Example response

{
  "123": {
    "id": 123,
    "type": "Child",
    "registered": "2025-10-15T10:33:16+00:00",
    "name": {
      "full": "John Smith",
      "given": "John",
      "middle": null,
      "family": "Smith",
      "parent": "John Smith"
    },
    "email": "john.smith@email.com",
    "phone": "+123.123345678",
    "reference": "3406038",
    "matriculation": null,
    "citizenship": "GB",
    "notes": null,
    "applications": "/api/v9/applicants/123/applications",
    "trackers": "/api/v9/applicants/123/trackers",
    "photo": "/api/v9/applicants/123/photo",
    "consents": {
      "1": {
        "decided": "2025-10-15T10:33:16+00:00",
        "decision": "Accept",
        "consent": "/api/v9/applicants/consents/1"
      },
      "2": {
        "decided": "2025-10-15T10:33:16+00:00",
        "decision": "Reject",
        "consent": "/api/v9/applicants/consents/2"
      },
      "4": {
        "decided": "2025-10-15T10:33:16+00:00",
        "decision": "Reject",
        "consent": "/api/v9/applicants/consents/4"
      }
    },
    "invoices": "/api/v9/applicants/123/invoices",
    "wishes": "/api/v9/applicants/123/wishes",
    "documents": "/api/v9/applicants/123/documents"
  }
}

POST Create an applicant

Create a new applicant/lead. The owner of the new account will be notified via email, using the applicant-welcome-api template. The welcome letter will also contain the account credentials needed for the applicant to start using his/her new account. Please include any additional instructions in the template — you can configure all templates using the admin interface (look for the Settings > Templates menu).

The URI for the new applicant account that was created is returned in the Location header.

Note that since this API request will send an email before returning, it is slightly slower than other API requests. This is a deliberate choice to avoid storing the (secrets-containing) email in more intermediate queues than required, while also guaranteeing that if the request succeeds, the email was accepted upstream.

If an applicant/lead with this email address exists, a 409 Conflict will be returned, along with the URI of the offending applicant in the Location header.

  POST /api/v9/applicants
  Host: apply.example.edu
  Authorization: DREAM apikey="..."

Parameters

Example request

curl \
  -X POST \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v9/applicants?email=john.smith@email.com&citizenship=GB&name=John%20Smith"

Response headers

Response codes