Scribd
Upload
2 views22 pages

API Documentation

The Hope Harvest API is a RESTful API that allows users to interact with various services such as user management, donations, and events using JSON data and JWT authentication. Key functionalities include user registration, donation processing, event creation, and tracking, with endpoints designed for both registered users and anonymous donors. The API is structured to ensure backward compatibility and includes features like error handling, rate limiting, and pagination.

Uploaded by

hasinarafat03
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
2 views22 pages

API Documentation

The Hope Harvest API is a RESTful API that allows users to interact with various services such as user management, donations, and events using JSON data and JWT authentication. Key functionalities include user registration, donation processing, event creation, and tracking, with endpoints designed for both registered users and anonymous donors. The API is structured to ensure backward compatibility and includes features like error handling, rate limiting, and pagination.

Uploaded by

hasinarafat03
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

Hope Harvest API Documentation

API Overview
The Hope Harvest API is organized around REST principles. All endpoints accept and return JSON data, use standard HTTP response
codes, and require authentication (except for public endpoints). The API is versioned to ensure backward compatibility.

Base URL: [Link] (example)

Authentication: JWT Bearer token in the Authorization header

Table of Contents
1. Authentication
2. User Service
3. Donation Service
4. Event Service
5. Volunteer Service
6. Fund Application Service
7. Error Handling
8. Rate Limiting
9. Pagination

Authentication
Obtain JWT Token
POST /auth/login

Authenticates a user and returns a JWT token for use in subsequent API calls.

Request Body:
{
"username": "string",
"password": "string"
}

Response (200 OK):


{
"accessToken": "string",
"tokenType": "Bearer",
"expiresIn": 3600,
"refreshToken": "string",
"userId": "uuid-string",
"roles": ["ROLE_ADMIN", "ROLE_DONOR"]
}

Refresh Token
POST /auth/refresh

Obtains a new access token using a refresh token.

Request Body:
{
"refreshToken": "string"
}

Response (200 OK):


{
"accessToken": "string",
"tokenType": "Bearer",
"expiresIn": 3600
}

Register User
POST /auth/register
Registers a new user account.

Request Body:
{
"username": "string",
"email": "string",
"password": "string",
"firstName": "string",
"lastName": "string"
}

Response (201 Created):


{
"userId": "uuid-string",
"username": "string",
"email": "string",
"roles": ["ROLE_USER"]
}

User Service
Get User Profile
GET /users/{userId}

Returns details of a user profile.

Path Parameters:

userId: UUID of the user

Response (200 OK):


{
"id": "uuid-string",
"username": "string",
"email": "string",
"firstName": "string",
"lastName": "string",
"roles": ["ROLE_DONOR"],
"createdAt": "2023-05-15T14:30:00Z",
"profilePicture": "url-string"
}

Update User Profile


PUT /users/{userId}

Updates a user's profile information.

Path Parameters:

userId: UUID of the user

Request Body:
{
"firstName": "string",
"lastName": "string",
"email": "string",
"profilePicture": "url-string"
}

Response (200 OK):


{
"id": "uuid-string",
"username": "string",
"email": "string",
"firstName": "string",
"lastName": "string",
"profilePicture": "url-string",
"updatedAt": "2023-05-15T14:30:00Z"
}

Change Password
PUT /users/{userId}/password
Changes a user's password.

Path Parameters:

userId: UUID of the user

Request Body:
{
"currentPassword": "string",
"newPassword": "string"
}

Response (200 OK):


{
"message": "Password updated successfully",
"updatedAt": "2023-05-15T14:30:00Z"
}

Get User Roles


GET /users/{userId}/roles

Returns the roles assigned to a user.

Path Parameters:

userId: UUID of the user

Response (200 OK):


{
"userId": "uuid-string",
"roles": [
{
"id": "role-uuid",
"name": "ROLE_ADMIN",
"permissions": ["CREATE_EVENT", "APPROVE_FUND"]
}
]
}

Assign Role to User


POST /users/{userId}/roles

Assigns a role to a user (Admin only).

Path Parameters:

userId: UUID of the user

Request Body:
{
"roleId": "uuid-string"
}

Response (200 OK):


{
"message": "Role assigned successfully",
"userId": "uuid-string",
"assignedRole": "ROLE_VOLUNTEER"
}

List Users
GET /users

Returns a paginated list of users (Admin only).

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
sort: Sort field (default: "username")
direction: Sort direction ("asc" or "desc", default: "asc")
role: Filter by role (optional)
Response (200 OK):
{
"content": [
{
"id": "uuid-string",
"username": "string",
"email": "string",
"firstName": "string",
"lastName": "string",
"roles": ["ROLE_DONOR"]
}
],
"page": 0,
"size": 20,
"totalElements": 100,
"totalPages": 5
}

Donation Service
Make Anonymous Donation
POST /donations/anonymous

Process an anonymous donation.

Request Body:
{
"amount": 100.00,
"currency": "USD",
"paymentMethod": "BKASH",
"paymentDetails": {
"phoneNumber": "string",
"transactionId": "string"
},
"eventId": "uuid-string", // Optional, for specific event
"notes": "string"
}

Response (201 Created):


{
"donationId": "uuid-string",
"amount": 100.00,
"currency": "USD",
"status": "PENDING",
"trackingId": "string",
"trackingKey": "string",
"createdAt": "2023-05-15T14:30:00Z",
"paymentInstructions": {
"nextSteps": "string",
"verificationUrl": "string"
}
}

Make Registered Donation


POST /donations/registered

Process a donation from a registered user.

Request Body:
{
"amount": 100.00,
"currency": "USD",
"paymentMethod": "BKASH",
"paymentDetails": {
"phoneNumber": "string",
"transactionId": "string"
},
"eventId": "uuid-string", // Optional, for specific event
"anonymous": false, // Whether to show donor name publicly
"notes": "string"
}

Response (201 Created):


{
"donationId": "uuid-string",
"amount": 100.00,
"currency": "USD",
"status": "PENDING",
"createdAt": "2023-05-15T14:30:00Z",
"paymentInstructions": {
"nextSteps": "string",
"verificationUrl": "string"
}
}

Track Donation
GET /donations/{donationId}/track

Track a donation status using ID (for registered users) or tracking ID and key (for anonymous).

Path Parameters:

donationId: UUID of the donation or tracking ID for anonymous

Query Parameters (for anonymous donations):

key: Tracking key

Response (200 OK):


{
"donationId": "uuid-string",
"amount": 100.00,
"currency": "USD",
"status": "COMPLETED",
"createdAt": "2023-05-15T14:30:00Z",
"completedAt": "2023-05-15T14:35:00Z",
"event": {
"id": "uuid-string",
"name": "Relief Drive",
"date": "2023-06-01T10:00:00Z"
},
"usage": [
{
"amount": 50.00,
"event": "Relief Drive",
"date": "2023-06-01T10:00:00Z",
"description": "Food packages"
}
]
}

Get User Donations


GET /donations/user/{userId}

Retrieve donations made by a specific user.

Path Parameters:

userId: UUID of the user

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
status: Filter by status (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"amount": 100.00,
"currency": "USD",
"status": "COMPLETED",
"createdAt": "2023-05-15T14:30:00Z",
"completedAt": "2023-05-15T14:35:00Z",
"event": {
"id": "uuid-string",
"name": "Relief Drive"
}
}
],
"page": 0,
"size": 20,
"totalElements": 5,
"totalPages": 1
}

Get Event Donations


GET /donations/event/{eventId}

Retrieve donations for a specific event.

Path Parameters:

eventId: UUID of the event

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
status: Filter by status (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"amount": 100.00,
"currency": "USD",
"status": "COMPLETED",
"donorName": "Anonymous", // or actual name if not anonymous
"createdAt": "2023-05-15T14:30:00Z"
}
],
"page": 0,
"size": 20,
"totalElements": 50,
"totalPages": 3,
"totalAmount": 5000.00
}

Get Donation Receipt


GET /donations/{donationId}/receipt

Generate a receipt for a completed donation.

Path Parameters:

donationId: UUID of the donation

Response (200 OK):


{
"receiptId": "string",
"donationId": "uuid-string",
"donorName": "string", // "Anonymous" for anonymous donations
"amount": 100.00,
"currency": "USD",
"dateCompleted": "2023-05-15T14:35:00Z",
"paymentMethod": "BKASH",
"transactionId": "string",
"event": {
"id": "uuid-string",
"name": "Relief Drive"
},
"receiptUrl": "url-to-pdf",
"organizationDetails": {
"name": "Hope Harvest Foundation",
"taxId": "string",
"address": "string",
"contact": "string"
}
}

Update Donation Usage


POST /donations/{donationId}/usage

Record how a donation was used (Admin only).

Path Parameters:
donationId: UUID of the donation

Request Body:
{
"eventId": "uuid-string",
"amount": 50.00,
"description": "Food packages",
"usageDate": "2023-06-01T10:00:00Z"
}

Response (200 OK):


{
"id": "uuid-string",
"donationId": "uuid-string",
"eventId": "uuid-string",
"amount": 50.00,
"description": "Food packages",
"usageDate": "2023-06-01T10:00:00Z",
"remainingAmount": 50.00
}

Event Service
Create Event (Admin)
POST /events

Create a new event (Admin only).

Request Body:
{
"title": "Relief Drive",
"description": "Distributing food and supplies to flood-affected areas",
"eventType": "RELIEF",
"startDate": "2023-06-01T10:00:00Z",
"endDate": "2023-06-01T18:00:00Z",
"location": {
"address": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"coordinates": {
"latitude": 0,
"longitude": 0
}
},
"budget": 5000.00,
"targetParticipants": 100,
"resources": [
{
"name": "Food packages",
"type": "SUPPLY",
"quantity": 100,
"notes": "string"
}
]
}

Response (201 Created):


{
"id": "uuid-string",
"title": "Relief Drive",
"description": "Distributing food and supplies to flood-affected areas",
"eventType": "RELIEF",
"startDate": "2023-06-01T10:00:00Z",
"endDate": "2023-06-01T18:00:00Z",
"status": "APPROVED",
"createdBy": "admin-uuid",
"createdAt": "2023-05-15T14:30:00Z",
"budget": 5000.00,
"location": {
"address": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"coordinates": {
"latitude": 0,
"longitude": 0
}
}
}

Request Event (Volunteer)


POST /events/request

Request a new event (Volunteer only).

Request Body:
{
"title": "Community Workshop",
"description": "Workshop on sustainable farming practices",
"eventType": "EDUCATION",
"startDate": "2023-06-15T09:00:00Z",
"endDate": "2023-06-15T12:00:00Z",
"location": {
"address": "string",
"city": "string",
"state": "string",
"zipCode": "string"
},
"estimatedBudget": 1000.00,
"targetParticipants": 30,
"justification": "This workshop will help local farmers improve crop yields",
"resources": [
{
"name": "Presentation equipment",
"type": "EQUIPMENT",
"quantity": 1,
"notes": "Projector and screen"
}
]
}

Response (201 Created):


{
"id": "uuid-string",
"title": "Community Workshop",
"description": "Workshop on sustainable farming practices",
"eventType": "EDUCATION",
"startDate": "2023-06-15T09:00:00Z",
"endDate": "2023-06-15T12:00:00Z",
"status": "PENDING",
"requestedBy": "volunteer-uuid",
"createdAt": "2023-05-15T14:30:00Z",
"estimatedBudget": 1000.00
}

List Events
GET /events

Get a paginated list of events.

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 10)
status: Filter by status (optional)
type: Filter by event type (optional)
startDate: Filter by start date (optional)
endDate: Filter by end date (optional)
upcoming: Boolean to show only upcoming events (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"title": "Relief Drive",
"eventType": "RELIEF",
"startDate": "2023-06-01T10:00:00Z",
"endDate": "2023-06-01T18:00:00Z",
"status": "APPROVED",
"location": {
"city": "string",
"state": "string"
},
"participantCount": 45,
"volunteerCount": 10
}
],
"page": 0,
"size": 10,
"totalElements": 25,
"totalPages": 3
}

Get Event Details


GET /events/{eventId}

Get detailed information about a specific event.

Path Parameters:

eventId: UUID of the event

Response (200 OK):


{
"id": "uuid-string",
"title": "Relief Drive",
"description": "Distributing food and supplies to flood-affected areas",
"eventType": "RELIEF",
"startDate": "2023-06-01T10:00:00Z",
"endDate": "2023-06-01T18:00:00Z",
"status": "APPROVED",
"createdBy": {
"id": "admin-uuid",
"name": "Admin Name"
},
"createdAt": "2023-05-15T14:30:00Z",
"budget": 5000.00,
"actualCost": 4500.00,
"location": {
"address": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"coordinates": {
"latitude": 0,
"longitude": 0
}
},
"participants": {
"registered": 75,
"attended": 50,
"volunteers": 10
},
"resources": [
{
"name": "Food packages",
"type": "SUPPLY",
"quantity": 100,
"allocated": true
}
],
"donations": {
"total": 6000.00,
"count": 40
}
}

Approve Event
PUT /events/{eventId}/approve

Approve an event request (Admin only).

Path Parameters:

eventId: UUID of the event

Request Body:
{
"approverComments": "string",
"adjustedBudget": 900.00 // Optional
}

Response (200 OK):


{
"id": "uuid-string",
"title": "Community Workshop",
"status": "APPROVED",
"approvedBy": "admin-uuid",
"approvedAt": "2023-05-16T10:00:00Z",
"approverComments": "string",
"budget": 900.00
}

Reject Event
PUT /events/{eventId}/reject

Reject an event request (Admin only).

Path Parameters:

eventId: UUID of the event

Request Body:
{
"rejectionReason": "string"
}

Response (200 OK):


{
"id": "uuid-string",
"title": "Community Workshop",
"status": "REJECTED",
"rejectedBy": "admin-uuid",
"rejectedAt": "2023-05-16T10:00:00Z",
"rejectionReason": "string"
}

Register for Event


POST /events/{eventId}/register

Register a user for an event.

Path Parameters:

eventId: UUID of the event

Request Body:
{
"userId": "uuid-string",
"role": "ATTENDEE", // ATTENDEE, VOLUNTEER
"notes": "string"
}

Response (201 Created):


{
"id": "uuid-string",
"eventId": "uuid-string",
"userId": "uuid-string",
"role": "ATTENDEE",
"registrationDate": "2023-05-16T10:00:00Z",
"status": "REGISTERED",
"notes": "string"
}

Get Event Participants


GET /events/{eventId}/participants

Get a list of participants for an event.

Path Parameters:

eventId: UUID of the event

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
role: Filter by role (optional)
status: Filter by status (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"userId": "uuid-string",
"name": "Participant Name",
"role": "ATTENDEE",
"registrationDate": "2023-05-16T10:00:00Z",
"status": "REGISTERED"
}
],
"page": 0,
"size": 20,
"totalElements": 75,
"totalPages": 4
}

Complete Event
PUT /events/{eventId}/complete

Mark an event as completed and record outcomes (Admin/Organizer only).

Path Parameters:

eventId: UUID of the event

Request Body:
{
"actualCost": 4500.00,
"attendeeCount": 50,
"summary": "The event was successful in providing relief to affected individuals",
"outcomes": [
{
"metric": "Food packages distributed",
"value": 95
}
],
"images": [
{
"url": "string",
"caption": "string"
}
]
}

Response (200 OK):


{
"id": "uuid-string",
"title": "Relief Drive",
"status": "COMPLETED",
"completedAt": "2023-06-01T18:30:00Z",
"actualCost": 4500.00,
"attendeeCount": 50,
"summary": "string"
}

Get Event Report


GET /events/{eventId}/report

Generate a comprehensive report for a completed event.

Path Parameters:

eventId: UUID of the event

Response (200 OK):


{
"event": {
"id": "uuid-string",
"title": "Relief Drive",
"eventType": "RELIEF",
"startDate": "2023-06-01T10:00:00Z",
"endDate": "2023-06-01T18:00:00Z",
"status": "COMPLETED",
"location": {
"city": "string",
"state": "string"
}
},
"financial": {
"budget": 5000.00,
"actualCost": 4500.00,
"totalDonations": 6000.00,
"donationCount": 40,
"breakdown": [
{
"category": "Food",
"amount": 3000.00
},
{
"category": "Transport",
"amount": 1500.00
}
]
},
"participation": {
"registered": 75,
"attended": 50,
"volunteers": 10
},
"outcomes": [
{
"metric": "Food packages distributed",
"value": 95
}
],
"summary": "string",
"images": [
{
"url": "string",
"caption": "string"
}
],
"volunteers": [
{
"name": "Volunteer Name",
"role": "Team Lead",
"hoursContributed": 8
}
]
}

Volunteer Service
Register as Volunteer
POST /volunteers

Register a user as a volunteer.

Request Body:
{
"userId": "uuid-string",
"bio": "string",
"skills": ["string"],
"availability": "WEEKENDS",
"categories": ["EDUCATION", "RELIEF"],
"experience": "string",
"motivation": "string",
"preferences": {
"remoteWork": true,
"localOnly": false,
"maxTravelDistance": 50
},
"references": [
{
"name": "string",
"contact": "string",
"relationship": "string"
}
]
}

Response (201 Created):


{
"id": "uuid-string",
"userId": "uuid-string",
"status": "PENDING",
"createdAt": "2023-05-16T10:00:00Z",
"applicationId": "uuid-string"
}

Get Volunteer Profile


GET /volunteers/{volunteerId}

Get a volunteer's profile.

Path Parameters:

volunteerId: UUID of the volunteer

Response (200 OK):


{
"id": "uuid-string",
"userId": "uuid-string",
"user": {
"name": "Volunteer Name",
"profilePicture": "url-string"
},
"bio": "string",
"skills": ["string"],
"availability": "WEEKENDS",
"categories": ["EDUCATION", "RELIEF"],
"status": "ACTIVE",
"badges": [
{
"id": "uuid-string",
"name": "First Year Milestone",
"description": "Completed one year of volunteering",
"awardedOn": "2023-05-01T00:00:00Z"
}
],
"statistics": {
"totalEvents": 10,
"totalHours": 80,
"averageRating": 4.5
},
"joinedAt": "2022-05-01T00:00:00Z"
}

Update Volunteer Profile


PUT /volunteers/{volunteerId}

Update a volunteer's profile information.

Path Parameters:

volunteerId: UUID of the volunteer

Request Body:
{
"bio": "string",
"skills": ["string"],
"availability": "WEEKENDS",
"categories": ["EDUCATION", "RELIEF"],
"preferences": {
"remoteWork": true,
"localOnly": false,
"maxTravelDistance": 50
}
}

Response (200 OK):


{
"id": "uuid-string",
"bio": "string",
"skills": ["string"],
"availability": "WEEKENDS",
"categories": ["EDUCATION", "RELIEF"],
"updatedAt": "2023-05-16T10:00:00Z"
}
Get Volunteer Badges
GET /volunteers/{volunteerId}/badges

Get badges earned by a volunteer.

Path Parameters:

volunteerId: UUID of the volunteer

Response (200 OK):


{
"volunteerId": "uuid-string",
"badges": [
{
"id": "uuid-string",
"name": "First Year Milestone",
"description": "Completed one year of volunteering",
"imageUrl": "url-string",
"awardedOn": "2023-05-01T00:00:00Z",
"criteria": "Complete 1 year of active volunteering"
}
],
"totalBadges": 5,
"nextBadges": [
{
"name": "Team Leader",
"description": "Lead a team of volunteers in an event",
"criteria": "Successfully lead a team of at least 5 volunteers in an event",
"progress": "0/1 events led"
}
]
}

Award Badge to Volunteer


POST /volunteers/{volunteerId}/badges

Award a badge to a volunteer (Admin only).

Path Parameters:

volunteerId: UUID of the volunteer

Request Body:
{
"badgeId": "uuid-string",
"notes": "string"
}

Response (201 Created):


{
"id": "uuid-string",
"volunteerId": "uuid-string",
"badgeId": "uuid-string",
"badge": {
"name": "Event Organizer",
"description": "Successfully organized an event"
},
"awardedOn": "2023-05-16T10:00:00Z",
"awardedBy": "admin-uuid",
"notes": "string"
}

Get Volunteer Ratings


GET /volunteers/{volunteerId}/ratings

Get ratings received by a volunteer.

Path Parameters:

volunteerId: UUID of the volunteer

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
Response (200 OK):
{
"content": [
{
"id": "uuid-string",
"eventId": "uuid-string",
"eventName": "Relief Drive",
"rating": 5,
"feedback": "Excellent work and coordination skills",
"ratedAt": "2023-06-02T10:00:00Z"
}
],
"page": 0,
"size": 20,
"totalElements": 10,
"totalPages": 1,
"averageRating": 4.5
}

Rate Volunteer
POST /volunteers/{volunteerId}/ratings

Submit a rating for a volunteer (Admin only).

Path Parameters:

volunteerId: UUID of the volunteer

Request Body:
{
"eventId": "uuid-string",
"rating": 5,
"feedback": "Excellent work and coordination skills"
}

Response (201 Created):


{
"id": "uuid-string",
"volunteerId": "uuid-string",
"eventId": "uuid-string",
"rating": 5,
"feedback": "Excellent work and coordination skills",
"ratedBy": "admin-uuid",
"ratedAt": "2023-05-16T10:00:00Z"
}

Assign Volunteer to Event


POST /volunteers/{volunteerId}/assignments

Assign a volunteer to an event (Admin only).

Path Parameters:

volunteerId: UUID of the volunteer

Request Body:
{
"eventId": "uuid-string",
"role": "TEAM_LEAD",
"notes": "string"
}

Response (201 Created):


{
"id": "uuid-string",
"volunteerId": "uuid-string",
"eventId": "uuid-string",
"role": "TEAM_LEAD",
"status": "PENDING",
"assignedBy": "admin-uuid",
"assignedAt": "2023-05-16T10:00:00Z",
"notes": "string"
}

Get Volunteer Assignments


GET /volunteers/{volunteerId}/assignments

Get assignments for a volunteer.

Path Parameters:

volunteerId: UUID of the volunteer

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
status: Filter by status (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"eventId": "uuid-string",
"event": {
"title": "Relief Drive",
"startDate": "2023-06-01T10:00:00Z",
"endDate": "2023-06-01T18:00:00Z",
"location": {
"city": "string",
"state": "string"
}
},
"role": "TEAM_LEAD",
"status": "ACCEPTED",
"assignedAt": "2023-05-16T10:00:00Z"
}
],
"page": 0,
"size": 20,
"totalElements": 5,
"totalPages": 1
}

Update Assignment Status


PUT /volunteers/assignments/{assignmentId}

Update the status of a volunteer assignment.

Path Parameters:

assignmentId: UUID of the assignment

Request Body:
{
"status": "ACCEPTED",
"notes": "string"
}

Response (200 OK):


{
"id": "uuid-string",
"volunteerId": "uuid-string",
"eventId": "uuid-string",
"status": "ACCEPTED",
"updatedAt": "2023-05-16T11:00:00Z",
"notes": "string"
}

Search Volunteers
GET /volunteers/search

Search for volunteers based on various criteria (Admin only).

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
skills: Comma-separated list of skills (optional)
categories: Comma-separated list of categories (optional)
availability: Availability type (optional)
location: Location search (optional)
status: Filter by status (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"userId": "uuid-string",
"name": "Volunteer Name",
"skills": ["string"],
"categories": ["EDUCATION", "RELIEF"],
"availability": "WEEKENDS",
"averageRating": 4.5,
"badges": 5,
"totalEvents": 10
}
],
"page": 0,
"size": 20,
"totalElements": 50,
"totalPages": 3
}

Fund Application Service


Submit Fund Application
POST /funds/applications

Submit an application for financial assistance.

Request Body:
{
"amount": 1000.00,
"purpose": "EDUCATION",
"description": "Financial assistance for college tuition",
"timeline": "IMMEDIATE",
"personalDetails": {
"fullName": "string",
"age": 20,
"gender": "string",
"occupation": "string",
"dependents": 0,
"currentIncome": 500.00
},
"contactDetails": {
"phoneNumber": "string",
"email": "string",
"address": {
"street": "string",
"city": "string",
"state": "string",
"zipCode": "string"
}
},
"bankDetails": {
"accountHolder": "string",
"accountNumber": "string",
"bankName": "string",
"branchCode": "string"
},
"additionalInformation": "string"
}

Response (201 Created):


{
"applicationId": "uuid-string",
"amount": 1000.00,
"purpose": "EDUCATION",
"status": "SUBMITTED",
"submittedAt": "2023-05-16T10:00:00Z",
"referenceNumber": "FND-2023-12345",
"nextSteps": "Your application will be reviewed by our team. You will be contacted for document verification."
}

Get Application Details


GET /funds/applications/{applicationId}

Get details of a fund application.

Path Parameters:

applicationId: UUID of the application

Response (200 OK):


{
"id": "uuid-string",
"referenceNumber": "FND-2023-12345",
"applicant": {
"id": "uuid-string",
"name": "Applicant Name"
},
"amount": 1000.00,
"purpose": "EDUCATION",
"description": "Financial assistance for college tuition",
"status": "SUBMITTED",
"timeline": "IMMEDIATE",
"submittedAt": "2023-05-16T10:00:00Z",
"personalDetails": {
"fullName": "string",
"age": 20,
"gender": "string",
"occupation": "string",
"dependents": 0,
"currentIncome": 500.00
},
"contactDetails": {
"phoneNumber": "string",
"email": "string",
"address": {
"street": "string",
"city": "string",
"state": "string",
"zipCode": "string"
}
},
"documents": [
{
"id": "uuid-string",
"documentType": "ID_PROOF",
"fileName": "string",
"uploadedAt": "2023-05-16T10:30:00Z",
"verified": false
}
],
"statusHistory": [
{
"status": "SUBMITTED",
"timestamp": "2023-05-16T10:00:00Z",
"notes": "string"
}
]
}

Upload Application Documents


POST /funds/applications/{applicationId}/documents

Upload supporting documents for a fund application.

Path Parameters:

applicationId: UUID of the application

Request Body (multipart/form-data):

documentType: Document type (ID_PROOF, INCOME_PROOF, etc.)


file: Document file
description: Document description (optional)

Response (201 Created):


{
"id": "uuid-string",
"applicationId": "uuid-string",
"documentType": "ID_PROOF",
"fileName": "string",
"fileSize": 1024,
"uploadedAt": "2023-05-16T10:30:00Z",
"status": "UPLOADED"
}

Assign Application to Volunteer


POST /funds/applications/{applicationId}/assign

Assign a fund application to a volunteer for verification (Admin only).

Path Parameters:

applicationId: UUID of the application

Request Body:
{
"volunteerId": "uuid-string",
"notes": "string",
"deadline": "2023-05-20T00:00:00Z"
}

Response (200 OK):


{
"applicationId": "uuid-string",
"volunteerId": "uuid-string",
"assignedBy": "admin-uuid",
"assignedAt": "2023-05-16T11:00:00Z",
"status": "ASSIGNED",
"deadline": "2023-05-20T00:00:00Z"
}

Verify Application
PUT /funds/applications/{applicationId}/verify

Submit verification results for a fund application (Volunteer only).

Path Parameters:

applicationId: UUID of the application

Request Body:
{
"verified": true,
"findings": "The applicant meets all eligibility criteria",
"recommendation": "APPROVE",
"suggestedAmount": 1000.00,
"documentVerifications": [
{
"documentId": "uuid-string",
"verified": true,
"notes": "string"
}
],
"additionalNotes": "string"
}

Response (200 OK):


{
"applicationId": "uuid-string",
"status": "VERIFIED",
"verifiedBy": "volunteer-uuid",
"verifiedAt": "2023-05-18T10:00:00Z",
"recommendation": "APPROVE",
"suggestedAmount": 1000.00
}

Approve Application
PUT /funds/applications/{applicationId}/approve

Approve a fund application (Admin only).

Path Parameters:

applicationId: UUID of the application

Request Body:
{
"approvedAmount": 900.00,
"notes": "string",
"disbursementSchedule": "ONE_TIME",
"conditions": "string"
}

Response (200 OK):


{
"applicationId": "uuid-string",
"status": "APPROVED",
"approvedBy": "admin-uuid",
"approvedAt": "2023-05-19T10:00:00Z",
"approvedAmount": 900.00,
"disbursementSchedule": "ONE_TIME"
}

Reject Application
PUT /funds/applications/{applicationId}/reject

Reject a fund application (Admin only).

Path Parameters:

applicationId: UUID of the application

Request Body:
{
"reason": "string",
"appealPossible": true,
"suggestedAlternatives": "string"
}

Response (200 OK):


{
"applicationId": "uuid-string",
"status": "REJECTED",
"rejectedBy": "admin-uuid",
"rejectedAt": "2023-05-19T10:00:00Z",
"reason": "string",
"appealPossible": true
}

Record Disbursement
POST /funds/applications/{applicationId}/disburse

Record a fund disbursement for an approved application (Admin only).

Path Parameters:

applicationId: UUID of the application

Request Body:
{
"amount": 900.00,
"disbursementMethod": "BANK_TRANSFER",
"transactionId": "string",
"notes": "string",
"disbursementDate": "2023-05-20T10:00:00Z"
}

Response (201 Created):


{
"id": "uuid-string",
"applicationId": "uuid-string",
"amount": 900.00,
"disbursementMethod": "BANK_TRANSFER",
"transactionId": "string",
"disbursedBy": "admin-uuid",
"disbursedAt": "2023-05-20T10:00:00Z",
"status": "COMPLETED"
}

Get User Applications


GET /funds/applications/user/{userId}

Get fund applications submitted by a user.

Path Parameters:

userId: UUID of the user

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
status: Filter by status (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"referenceNumber": "FND-2023-12345",
"purpose": "EDUCATION",
"amount": 1000.00,
"status": "APPROVED",
"submittedAt": "2023-05-16T10:00:00Z",
"lastUpdated": "2023-05-19T10:00:00Z"
}
],
"page": 0,
"size": 20,
"totalElements": 3,
"totalPages": 1
}

Get Assigned Applications


GET /funds/applications/volunteer/{volunteerId}

Get fund applications assigned to a volunteer.

Path Parameters:

volunteerId: UUID of the volunteer

Query Parameters:

page: Page number (default: 0)


size: Page size (default: 20)
status: Filter by status (optional)

Response (200 OK):


{
"content": [
{
"id": "uuid-string",
"referenceNumber": "FND-2023-12345",
"applicantName": "Applicant Name",
"purpose": "EDUCATION",
"amount": 1000.00,
"status": "ASSIGNED",
"assignedAt": "2023-05-16T11:00:00Z",
"deadline": "2023-05-20T00:00:00Z"
}
],
"page": 0,
"size": 20,
"totalElements": 5,
"totalPages": 1
}

Error Handling
All API errors follow a standard format to ensure consistent error handling across the application.

Error Response Format


{
"status": 400,
"error": "Bad Request",
"message": "Invalid input data",
"path": "/api/endpoint",
"timestamp": "2023-05-16T10:00:00Z",
"details": [
{
"field": "email",
"message": "must be a valid email address"
}
]
}

Common Error Codes


400 Bad Request: Invalid request parameters or payload
401 Unauthorized: Missing or invalid authentication
403 Forbidden: Authenticated but insufficient permissions
404 Not Found: Resource not found
409 Conflict: Request conflicts with current state
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server-side error

Rate Limiting
The API implements rate limiting to prevent abuse and ensure fair usage.

Anonymous requests: 30 requests per minute


Authenticated users: 60 requests per minute
Admin users: 120 requests per minute

Rate limit headers are included in all responses:


X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1621159200

When rate limit is exceeded, a 429 Too Many Requests response is returned.

Pagination
List endpoints support pagination through query parameters:

page: Page number (zero-based, default: 0)


size: Page size (default: 20, max: 100)
sort: Field to sort by (default varies by endpoint)
direction: Sort direction ("asc" or "desc", default: "asc")

Pagination details are included in the response:


{
"content": [...],
"page": 0,
"size": 20,
"totalElements": 100,
"totalPages": 5
}

Common questions

Powered by AI

The integration of secure payment methods like BKASH ensures transactional efficiency by providing donors with convenient and reliable options. It impacts donor confidence positively as secure transactions reduce risk and build trust in the donation process, thereby enhancing donor satisfaction and potentially increasing donation volumes .

Volunteer assignments are managed by assigning specific roles such as TEAM_LEAD, with each assignment status—'PENDING', 'ACCEPTED', 'REJECTED'—tracked over time. These roles define volunteer responsibilities within events and ensure that qualifications align with tasks. Admins oversee this process, monitoring changes and status updates to manage workload distribution effectively .

Volunteer badges serve as recognition and motivational tools by commemorating milestones and leadership achievements, encouraging continued involvement. Badges are awarded when certain criteria, such as completing a year of service or leading an event, are met. Admins assign these formally according to documented achievements and service metrics .

When a volunteer submits a new event request, they must provide details such as the title, description, event type, dates, location, budget estimation, target participants, justification, and required resources. The request becomes 'PENDING' and awaits admin approval, which could involve adjustments in budget or rejection based on provided justification and needs .

Donation usage is tracked by recording how the donated funds are utilized, with details being updated by an admin. This process ensures transparency by specifying amounts spent, descriptions of the usage, and the dates associated with the expenditure . This transparency requires admin authority for recording usage and is crucial for donor trust and organizational accountability.

Anonymity in the donation process is maintained by not requiring the donor's name, but necessary payment details such as phone number and transaction ID are still required, along with the donation amount, currency, and optional event ID for further specificity .

The approval or rejection of a fund application hinges on the verification details provided by volunteers, such as eligibility criteria and documentation, followed by an admin decision. Admins consider the volunteer's recommendations and provided notes, either approving with adjustments or rejecting with specified reasons and alternatives offered for appeal .

After an event is marked as completed by the admin or organizer, a detailed report is generated. It includes actual costs compared to the budget, donations received, attendance figures, and outcomes accomplished, such as metrics like distributed goods. This facilitates a thorough evaluation against initial targets and financial planning .

Upon being assigned a fund application for verification, a volunteer needs to submit verification results including whether the application is verified, detailed findings such as if the applicant meets all eligibility criteria, a recommendation for approval or otherwise, a suggested amount for disbursement, and document verification notes .

The success of a relief event is measured through metrics such as the number of registered vs. attended participants, volunteer involvement, and resources utilized. Reports include financial data comparing budget vs. actual costs, outcomes like distributed packages, attendance, and participant feedback, providing a comprehensive view of both engagement and resource effectiveness .

You might also like