Applicants

Represents a list of applicants or leads registered in DreamApply.

/api/v10/applicants

GET List applicants

List applicants or leads that match the specified filter parameters. The number of applicants or leads is returned in the X-Count header.

GET /api/v10/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, meaning an applicant is included if it matches any value in the list.
• Note [2]: You can use either tracker IDs or codes to reference trackers. However, IDs are guaranteed not to change while the tracker codes may change over time.
• Note [3]: Some elements in the returned objects are links to other API requests. Using the expand parameter, you can expand this data to the actual records, saving additional API requests. The full list of possible expansions is trackers,documents,consents,invoices,wishes. To request multiple expansions, combine them as a comma-separated list in the expand parameter. Using this parameter caps to limit to 16384 for performance reasons.
• Note [4]: An ISO 8601 compatible datetime 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 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/v10/applicants?bySince=2025-10-01T00:00:00Z&byCitizenships=US,GB&expand=trackers&limit=5"

Response headers

Response codes

Example response

{
  "123": {
    "id": 123,
    "type": "Child",
    "registered": "2025-10-15T10:33:16+00:00",
    "name": {
      "full": "Emily Williams",
      "given": "Emily",
      "middle": null,
      "family": "Williams",
      "parent": "Jane Williams"
    },
    "email": "e.williams@email.com",
    "phone": "+1234567890",
    "reference": "1234567",
    "matriculation": "ABC123",
    "citizenship": "GB",
    "notes": "Strong candidate",
    "applications": "/api/v10/applicants/123/applications",
    "trackers": {
      "10": {
        "assigned": "2026-04-08T12:58:25+00:00",
        "tracker": "/api/v10/applicants/trackers/10"
      }
    },
    "photo": "/api/v10/applicants/123/photo",
    "consents": "/api/v10/applicants/123/consents",
    "invoices": "/api/v10/applicants/123/invoices",
    "wishes": "/api/v10/applicants/123/wishes"
  },
  "124": {
    "id": 124,
    "type": "Natural",
    "registered": "2025-11-24T10:56:34+00:00",
    "name": {
      "full": "John Smith",
      "given": "John",
      "middle": "A",
      "family": "Smith"
    },
    "email": "john.smith@email.com",
    "phone": "",
    "reference": "1234568",
    "matriculation": "ABC124",
    "citizenship": "GB",
    "notes": "Needs review",
    "applications": "/api/v10/applicants/124/applications",
    "trackers": {
      "11": {
        "assigned": "2026-04-08T12:58:25+00:00",
        "tracker": "/api/v10/applicants/trackers/11"
      }
    },
    "photo": "/api/v10/applicants/124/photo",
    "consents": "/api/v10/applicants/124/consents",
    "invoices": "/api/v10/applicants/124/invoices",
    "wishes": "/api/v10/applicants/124/wishes"
  }
}

POST Create an applicant

Create a new applicant or lead in DreamApply.

When a new applicant or lead is registered, DreamApply sends a welcome email to the account owner using the applicant-welcome-api template. The email contains the account credentials that the applicant needs to log in to DreamApply. If necessary, you can edit this template using the Settings > Templates view in the DreamApply portal to include additional instructions.

Since this API request sends a welcome email before returning a response, it takes slightly longer to complete than other requests. This behavior is intentional to avoid storing sensitive email data in intermediate queues and to guarantee that the upstream server accepts the email before the request succeeds.

If an applicant or lead with the specified email address already exists, the request returns the 409 Conflict error and includes the URI of the existing applicant in the Location header.

  POST /api/v10/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/v10/applicants?email=john.smith@email.com&citizenship=GB&name=John%20Smith"

Response headers

Response codes