Application Workflow

Applications can be submitted through the public form, the donor portal API, or the public API endpoint. Each application captures the applicant’s responses, optional attachments, and tracks progress through review stages.

ScholarshipApplication model

Field	Type	Description
id	UUID	Primary key
foundation_id	UUID	Owning foundation
scholarship_id	UUID	The scholarship being applied to
contact_id	UUID	The applicant (auto-created if new)
responses	JSON?	Answers to the scholarship’s form_fields
attachments	JSON?	File paths or URLs for uploaded documents
stage	ApplicationStage	Review pipeline position
reviewer_notes	string?	Internal notes from reviewers
source	ApplicationSource	How the application was submitted
submitted_at	datetime?	When the application was submitted

Application stages

The ApplicationStage enum defines the review pipeline:

Stage	Value	Description
New	new	Just submitted, not yet reviewed
Under Review	under_review	Being evaluated by the foundation
Accepted	accepted	Approved for an award
Declined	declined	Not selected

Stage transitions

new → under_review → accepted
                   → declined

Stage updates are performed via PATCH /api/applications/{id}/stage and trigger:

1. The application’s stage field is updated
2. An activity is logged on the contact’s timeline
3. A status notification email is sent to the applicant

Application sources

The ApplicationSource enum tracks how each application was submitted:

Source	Value	Description
Form	form	Public Blade-rendered form at /scholarships/{foundationSlug}/{scholarshipSlug}
API	api	Submitted via REST API
Webhook	webhook	Received from an external system

Submission flow

The ScholarshipService::createApplication() method handles the full intake:

public function createApplication(
    Scholarship $scholarship,
    array $data,        // {email, first_name?, last_name?, responses?, attachments?}
    ApplicationSource $source,
): ScholarshipApplication;

What happens during submission

1. Contact resolution — Finds or creates a contact by email within the foundation
2. Relationship assignment — Adds the applicant relationship type to the contact
3. Application creation — Creates the ScholarshipApplication record with stage new
4. Activity logging — Records ActivityType::ApplicationSubmitted on the contact’s timeline
5. Confirmation email — Sends “Application Received” email to the applicant via EmailService

Public submission endpoints

Blade form (browser)

GET  /scholarships/{foundationSlug}/{scholarshipSlug}          # Show form
POST /scholarships/{foundationSlug}/{scholarshipSlug}          # Submit form
GET  /scholarships/{foundationSlug}/{scholarshipSlug}/confirmation  # Thank you page

API (no auth required)

POST /api/scholarships/applications
Content-Type: application/json

{
  "scholarship_id": "uuid-here",
  "email": "applicant@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "responses": {
    "gpa": "3.8",
    "essay": "I believe in..."
  }
}

Donor portal (authenticated)

POST /api/donor/applications

Managing applications

List applications for a scholarship

GET /api/scholarships/{scholarshipId}/applications

View a single application

GET /api/applications/{applicationId}

Update stage

PATCH /api/applications/{applicationId}/stage
Content-Type: application/json

{
  "stage": "under_review",
  "notes": "Strong essay, reviewing transcripts"
}

Delete an application

DELETE /api/applications/{applicationId}

Relationships

Relationship	Type	Target
foundation()	BelongsTo	Foundation
scholarship()	BelongsTo	Scholarship
contact()	BelongsTo	Contact