Application

Represents application contents (data input by the application).

URI
/api/v9/applications/ID

GET Get an application

Get the application contents (data input by the application). Does not include documents, flags, offers, exports etc. Use separate API requests to retrieve those.

Syntax
GET /api/v9/applications/123
Host: apply.example.edu
Authorization: DREAM apikey="..."

Parameters

NameRequired/OptionalDescriptionNotes
expandOptionalExpand the chosen relational element(s), for example applicant,offer[1]

Notes

Note [1]: 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 applicant,flags,courses,offers,documents,tasks,scores,references. You can set one or multiple expansions, combining them in a comma-separated fashion to the expand parameter.

Example request

Request
curl
curl \
  -X GET \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v9/applications/123?expand=courses,offers"

Response headers

HeaderValueDescription
Content-Typeapplication/jsonMedia type of the resource
Content-Length1456Size of the response body in bytes

Response codes

Response codeDescription
200 OKApplication data was successfully returned
404 Not FoundThe application was not found

Example response

Response
{
  "profile": {
    "name": {
      "given": "Sofia",
      "family": "Pereira"
    },
    "idcode": "99010156789",
    "passport": {
      "number": "T1234567890B",
      "issue": "2020-08-15",
      "expiry": "2030-08-14"
    },
    "birth": {
      "date": "1999-10-01",
      "place": "Lisbon"
    },
    "nationality": "PT",
    "citizenship": "PT",
    "gender": "F",
    "marital": "S"
  },
  "legal": {},
  "contact": {
    "address": {
      "street": "Rua do Sol, 5-3º Dto",
      "municipality": "Lisbon",
      "postalcode": "1200-123",
      "country": "PT"
    },
    "telephone": {
      "day": "+351215551234",
      "evening": "+351215551234",
      "mobile": "+351912345678"
    },
    "email": "sofia.pereira.application@example.com",
    "emergency": {
      "name": "Pedro Mendes (Father)",
      "telephone": "+351961112233"
    }
  },
  "home": {},
  "host": {},
  "grades": [
    {
      "id": "8",
      "score": "92",
      "date": "2024-06-15"
    },
    {
      "id": "6",
      "score": "88",
      "date": "2024-05-20"
    },
    {
      "id": "3",
      "score": "95",
      "date": "2024-05-27"
    }
  ],
  "education": [
    {
      "level": "SE",
      "graduation": "2017-06",
      "institution": "Escola Secundária de Eça de Queirós",
      "country": "PT",
      "programme": {
        "name": "Science and Technology"
      }
    },
    {
      "level": "BA",
      "graduation": "2021-06",
      "institution": "University of Lisbon",
      "country": "PT",
      "programme": {
        "name": "BSc in Computer Science"
      }
    },
    {
      "level": "MA",
      "graduation": "2023-12",
      "institution": "Imperial College London",
      "country": "GB",
      "programme": {
        "name": "MSc in Artificial Intelligence"
      }
    }
  ],
  "languages": {
    "0": {
      "name": "en",
      "proficiency": "C2",
      "experience": "10",
      "information": "IELTS 8.0"
    },
    "1": {
      "name": "es",
      "proficiency": "B2",
      "experience": "4"
    },
    "2": {
      "name": "fr",
      "proficiency": "A2",
      "experience": "1"
    },
    "native": "pt"
  },
  "career": [
    {
      "employer": "TechInnovate Solutions",
      "position": "Junior Data Scientist",
      "period": {
        "from": "2024-01",
        "to": "2025-06"
      },
      "weekly": "40"
    },
    {
      "employer": "Startup Accelerator Lda.",
      "position": "AI Research Intern",
      "period": {
        "from": "2023-07",
        "to": "2023-12"
      },
      "weekly": "20"
    }
  ],
  "activities": [
    {
      "organization": "Women in Tech Portugal",
      "nature": "Mentor for university students in STEM fields.",
      "period": {
        "from": "2024-03",
        "to": "2025-12"
        }
      }
    }
  ],
  "residences": [
    {
      "country": "GB",
      "purpose": "Studying",
      "period": {
        "from": "2022-09",
        "to": "2023-12"
        }
      }
    }
  ],
  "visa": {},
  "motivation": [
    {
      "general": "\n\t\tI am writing to express my keen interest in the Doctoral Programme in Advanced Robotics and Autonomous Systems for the Fall 2025 intake. My master's research at Imperial College London focused on novel deep learning architectures for sensor data fusion, an area which aligns perfectly with the research focus of your Robotics Lab on embodied AI and real-time navigation.\n\nYour recent publication on bio-inspired control systems, in particular, resonated strongly with my goal to contribute meaningful innovation to the field of autonomous vehicles. I believe my academic background in computer science and AI, coupled with practical experience in data science at TechInnovate Solutions, has prepared me well to undertake the rigorous research required for a PhD at your esteemed institution. I am eager to leverage the state-of-the-art facilities and collaborate with your pioneering faculty to push the boundaries of robust, deployable autonomous systems. My long-term aspiration is to develop ethical, human-centric AI and I view this program as the essential next step in that journey.\t\n\t\t",
      "course": null
    }
  ],
  "misc": {
    "channel": {
      "other": "Attended a virtual open day hosted on YouTube and received an email from an alumnus.",
      "name": "Alumni referral"
    }
  },
  "signature": {},
  "reference": {},
  "id": 123,
  "created": "2024-10-20T10:30:00+00:00",
  "revised": "2025-01-05T11:45:00+00:00",
  "submitted": "2024-12-15T16:00:00+00:00",
  "status": "In Review",
  "category": {
    "id": 2,
    "title": "International (Non-EU)",
    "colour": "#3366ff",
    "mode": "Public"
  },
  "academic_term": "/api/v9/academic-terms/5",
  "applicant": "/api/v9/applicants/123",
  "flags": "/api/v9/applications/123/flags",
  "courses": {
    "4": {
      "priority": 1,
      "submitted": "2024-12-15T16:00:00+00:00",
      "deadline": "2025-03-31T23:59:59+00:00",
      "course": "/api/v9/courses/101",
      "intake": "/api/v9/intakes/5",
      "modifier": null
    }
  },
  "offers": {
    "12": {
      "id": 12,
      "priority": 1,
      "inserted": "2025-02-10T09:00:00+00:00",
      "saved": "2025-02-10T09:00:00+00:00",
      "confirmed": null,
      "course": "/api/v9/courses/101",
      "intake": "/api/v9/intakes/5",
      "comments": "Congratulations, the admissions committee is pleased to offer you admission to the program.",
      "comments-confirmed": null,
      "decision": "Pending",
      "decision-policy": "Standard",
      "decision-deadline": "2025-03-01T23:59:59+00:00",
      "decided": null,
      "score": {
        "auto": "95.5000",
        "extra": "12.00"
      },
      "scored": "2025-02-05T10:10:20+00:00",
      "notes": "/api/v9/applications/123/offers/12/notes",
      "subject": "Conditional Offer of Admission: Doctoral Programme in Advanced Robotics",
      "type": "Conditional",
      "type-confirmed": null,
      "type-reason": {
        "id": null,
        "reason": null
      }
    }
  },
  "exports": "/api/v9/applications/123/exports",
  "documents": "/api/v9/applications/123/documents",
  "references": "/api/v9/applications/123/references",
  "scores": "/api/v9/applications/123/scores",
  "tasks": "/api/v9/applications/123/tasks",
  "pdf": "/api/v9/applications/123/pdf"
}
Response
{
  "profile": {
    "name": {
      "given": "Sofia",
      "family": "Pereira"
    },
    "idcode": "99010156789",
    "passport": {
      "number": "T1234567890B",
      "issue": "2020-08-15",
      "expiry": "2030-08-14"
    },
    "birth": {
      "date": "1999-10-01",
      "place": "Lisbon"
    },
    "nationality": "PT",
    "citizenship": "PT",
    "gender": "F",
    "marital": "S"
  },
  "legal": {},
  "contact": {
    "address": {
      "street": "Rua do Sol, 5-3º Dto",
      "municipality": "Lisbon",
      "postalcode": "1200-123",
      "country": "PT"
    },
    "telephone": {
      "day": "+351215551234",
      "evening": "+351215551234",
      "mobile": "+351912345678"
    },
    "email": "sofia.pereira.application@example.com",
    "emergency": {
      "name": "Pedro Mendes (Father)",
      "telephone": "+351961112233"
    }
  },
  "home": {},
  "host": {},
  "grades": [
    {
      "id": "8",
      "score": "92",
      "date": "2024-06-15"
    },
    {
      "id": "6",
      "score": "88",
      "date": "2024-05-20"
    },
    {
      "id": "3",
      "score": "95",
      "date": "2024-05-27"
    }
  ],
  "education": [
    {
      "level": "SE",
      "graduation": {
        "yy": "2017",
        "mm": "07"
      },
      "institution": "Escola Secundária de Eça de Queirós",
      "country": "PT",
      "programme": {
        "name": "Science and Technology"
      }
    },
    {
      "level": "BA",
      "graduation": {
        "yy": "2021"
      },
      "institution": "University of Lisbon",
      "country": "PT",
      "programme": {
        "name": "BSc in Computer Science"
      }
    },
    {
      "level": "MA",
      "graduation": {
        "yy": "2023",
        "mm": "12"
      },
      "institution": "Imperial College London",
      "country": "GB",
      "programme": {
        "name": "MSc in Artificial Intelligence"
      }
    }
  ],
  "languages": {
    "0": {
      "name": "en",
      "proficiency": "C2",
      "experience": "10",
      "information": "IELTS 8.0"
    },
    "1": {
      "name": "es",
      "proficiency": "B2",
      "experience": "4"
    },
    "2": {
      "name": "fr",
      "proficiency": "A2",
      "experience": "1"
    },
    "native": "pt"
  },
  "career": [
    {
      "employer": "TechInnovate Solutions",
      "position": "Junior Data Scientist",
      "period": {
        "from": {
          "yy": "2024",
          "mm": "01"
        },
        "to": {
          "yy": "2025",
          "mm": "06"
        }
      },
      "weekly": "40"
    },
    {
      "employer": "Startup Accelerator Lda.",
      "position": "AI Research Intern",
      "period": {
        "from": {
          "yy": "2023",
          "mm": "07"
        },
        "to": {
          "yy": "2023",
          "mm": "12"
        }
      },
      "weekly": "20"
    }
  ],
  "activities": [
    {
      "organization": "Women in Tech Portugal",
      "nature": "Mentor for university students in STEM fields.",
      "period": {
        "from": {
          "yy": "2024",
          "mm": "03"
        },
        "to": {
          "yy": "2025",
          "mm": "12"
        }
      }
    }
  ],
  "residences": [
    {
      "country": "GB",
      "purpose": "Studying",
      "period": {
        "from": {
          "yy": "2022",
          "mm": "09"
        },
        "to": {
          "yy": "2023",
          "mm": "12"
        }
      }
    }
  ],
  "visa": {},
  "motivation": [
    {
      "general": "\n\t\tI am writing to express my keen interest in the Doctoral Programme in Advanced Robotics and Autonomous Systems for the Fall 2025 intake. My master's research at Imperial College London focused on novel deep learning architectures for sensor data fusion, an area which aligns perfectly with the research focus of your Robotics Lab on embodied AI and real-time navigation.\n\nYour recent publication on bio-inspired control systems, in particular, resonated strongly with my goal to contribute meaningful innovation to the field of autonomous vehicles. I believe my academic background in computer science and AI, coupled with practical experience in data science at TechInnovate Solutions, has prepared me well to undertake the rigorous research required for a PhD at your esteemed institution. I am eager to leverage the state-of-the-art facilities and collaborate with your pioneering faculty to push the boundaries of robust, deployable autonomous systems. My long-term aspiration is to develop ethical, human-centric AI and I view this program as the essential next step in that journey.\t\n\t\t",
      "course": null
    }
  ],
  "misc": {
    "channel": {
      "other": "Attended a virtual open day hosted on YouTube and received an email from an alumnus.",
      "name": "Alumni referral"
    }
  },
  "signature": {},
  "reference": {},
  "id": 123,
  "created": "2024-10-20T10:30:00+00:00",
  "revised": "2025-01-05T11:45:00+00:00",
  "submitted": "2024-12-15T16:00:00+00:00",
  "status": "In Review",
  "category": {
    "id": 2,
    "title": "International (Non-EU)",
    "colour": "#3366ff",
    "mode": "Public"
  },
  "academic_term": "/api/v9/academic-terms/5",
  "applicant": "/api/v9/applicants/123",
  "flags": "/api/v9/applications/123/flags",
  "courses": {
    "4": {
      "priority": 1,
      "submitted": "2024-12-15T16:00:00+00:00",
      "deadline": "2025-03-31T23:59:59+00:00",
      "course": "/api/v9/courses/101",
      "intake": "/api/v9/intakes/5",
      "modifier": null
    }
  },
  "offers": {
    "12": {
      "id": 12,
      "priority": 1,
      "inserted": "2025-02-10T09:00:00+00:00",
      "saved": "2025-02-10T09:00:00+00:00",
      "confirmed": null,
      "course": "/api/v9/courses/101",
      "intake": "/api/v9/intakes/5",
      "comments": "Congratulations, the admissions committee is pleased to offer you admission to the program.",
      "comments-confirmed": null,
      "decision": "Pending",
      "decision-policy": "Standard",
      "decision-deadline": "2025-03-01T23:59:59+00:00",
      "decided": null,
      "score": {
        "auto": "95.5000",
        "extra": "12.00"
      },
      "scored": "2025-02-05T10:10:20+00:00",
      "notes": "/api/v9/applications/123/offers/12/notes",
      "subject": "Conditional Offer of Admission: Doctoral Programme in Advanced Robotics",
      "type": "Conditional",
      "type-confirmed": null,
      "type-reason": {
        "id": null,
        "reason": null
      }
    }
  },
  "exports": "/api/v9/applications/123/exports",
  "documents": "/api/v9/applications/123/documents",
  "references": "/api/v9/applications/123/references",
  "scores": "/api/v9/applications/123/scores",
  "tasks": "/api/v9/applications/123/tasks",
  "pdf": "/api/v9/applications/123/pdf"
}

PATCH Update an application

Update specific fields in an existing application.

This request is supported in API version 9 and later.

Supported sections

You can update the following sections of an application:

  • Profile
  • Legal entity information (for applications submitted on behalf of legal entities)
  • Contacts (except the contact email)
  • Education
  • Languages
  • Career
  • Activities
  • Residences
  • Custom sections (for details, see Create custom sections)

Data validation

When processing the request, the API performs data integrity checks such as:

  • Phone number validation: The field must contain a valid phone number
  • Country code validation: The field must contain a correct ISO alpha2 country identifier

If a validation check fails, the API rejects the request and returns an error description.

Syntax
PATCH /api/v9/applications/123
Host: apply.example.edu
Authorization: DREAM apikey="..."

Raw request body

The request body must be a valid JSON object containing only the fields you want to update. Fields omitted from the request body remain unchanged.

The request follows the JSON Merge Patch rules defined in RFC 7396:

  • Update values: Include the fields with their new values.
  • Add fields/arrays: Include the fields/arrays with their values. Arrays are replaced in full and are not merged element by element.
  • Delete an array: Set the value to [].
Request body
{
  "education": [
    {
      "level": "BA",
      "graduation": "2026-06-01",
      "institution": "Yale University"
    },
    {
      "level": "SE",
      "graduation": "2027-02-01",
      "institution": "Ohio Middle School"
    }
  ]
}

Example request

Request
curl
curl -X PATCH \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  -d '{
    "education": [
      {
        "level": "BA",
        "graduation": "2026-06-01",
        "institution": "Yale University"
      },
      {
        "level": "SE",
        "graduation": "2027-02-01",
        "institution": "Ohio Middle School"
      }
    ]
  }' \
  "https://apply.example.edu/api/v9/applications/123"
Request
curl
curl -X PATCH \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  -d '{
    "education": []
  }' \
  "https://apply.example.edu/api/v9/applications/123"

Response headers

HeaderValueDescription
Content-Typetext/html; charset=UTF-8Media type of the resource

Response codes

Response codeDescription
200 OKThe application data was successfully updated
400 Bad RequestThis API request is available starting from version 9, use
PATCH /api/applications/$ID
400 Bad RequestInvalid application data, make sure that the body contains a valid JSON
400 Bad RequestThe supplied JSON data appears to contain extraneous elements
that were not recognised: field.name
400 Bad RequestField: profile.citizenship
Error: The value is not a correct ISO alpha2 country identifier
400 Bad RequestField: contact.telephone.mobile
Error: The supplied value does not seem to be a telephone number