Skip to main content

Useless Call Form API

Author:{}

Last Updated: 2026-02-11
Version: v1.0

Base URL: https://api.fursahub.com/api/v1

Short Description: The Useless Call Form API manages application forms for calls/opportunities posted on the FursaHub platform. It handles the complete lifecycle of application forms from creation through submission to review and approval/rejection. This API enables users to apply to calls by filling out detailed application forms and allows call owners to manage and review submitted applications.

Hints:

  • All endpoints require authentication via Bearer token unless specified otherwise
  • Form submissions cannot be edited after the status changes from DRAFT to SUBMITTED
  • Call owners can only view forms with status SUBMITTED, UNDER_REVIEW, APPROVED, or REJECTED
  • Applicants can save forms multiple times while in DRAFT status
  • One user can only have one application per call (duplicate prevention)
  • Page numbers start from 1 (not 0)
  • Default pagination size is 20 items per page
  • All timestamps are in ISO 8601 format
  • File uploads (documents, certificates) should be handled separately and only URLs are stored in the form

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2026-02-11T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2026-02-11T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field Type Description
success boolean Always true for successful operations, false for errors
httpStatus string HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
message string Human-readable message describing the operation result
action_time string ISO 8601 timestamp of when the response was generated
data object/string Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

  • GET - GET - Green (Safe, read-only operations)
  • POST - POST - Blue (Create new resources)
  • PUT - PUT - Yellow (Update/replace entire resource)
  • PATCH - PATCH - Orange (Partial updates)
  • DELETE - DELETE - Red (Remove resources)

Endpoints

1. Start Application Form

Purpose: Initialize a new application form for a specific call application in DRAFT status

Endpoint: POST {base_url}/useless-forms/applications/{applicationId}/start

Access Level: 🔒 Protected (Requires Bearer Token - Must be the application owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
applicationId UUID Yes Unique identifier of the call application Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form started successfully",
  "action_time": "2026-02-11T10:30:45",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "applicationId": "660e8400-e29b-41d4-a716-446655440001",
    "callId": "770e8400-e29b-41d4-a716-446655440002",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "applicationStatus": "DRAFT",
    "createdAt": "2026-02-11T10:30:45",
    "updatedAt": "2026-02-11T10:30:45"
  }
}

Success Response Fields:

Field Description
id Unique identifier of the form
applicationId Reference to the call application
callId Reference to the call this form belongs to
userId ID of the user who created the form
applicationStatus Current status of the form (always DRAFT when starting)
createdAt Timestamp when the form was created
updatedAt Timestamp when the form was last updated

Error Response Examples:

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "User not authenticated",
  "action_time": "2026-02-11T10:30:45",
  "data": "User not authenticated"
}

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Not authorized",
  "action_time": "2026-02-11T10:30:45",
  "data": "Not authorized"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Application not found",
  "action_time": "2026-02-11T10:30:45",
  "data": "Application not found"
}

2. Save Form Draft

Purpose: Save or update form data while keeping it in DRAFT status (can be called multiple times)

Endpoint: PUT {base_url}/useless-forms/applications/{applicationId}/draft

Access Level: 🔒 Protected (Requires Bearer Token - Must be the form owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
applicationId UUID Yes Unique identifier of the call application Must be valid UUID format

Request JSON Sample:

{
  "whoIsApplying": "MYSELF",
  "fullName": "John Doe",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "phoneNumber": "+255712345678",
  "countryCode": "+255",
  "nationality": "Tanzanian",
  "preferredContactMethod": "EMAIL",
  "profilePictureUrl": "https://storage.example.com/profiles/john.jpg",
  "employmentStatus": "EMPLOYED",
  "employerName": "Tech Solutions Ltd",
  "jobTitle": "Software Engineer",
  "employmentType": "FULL_TIME",
  "dateOfBirth": "1990-05-15",
  "placeOfBirth": "Dar es Salaam",
  "sex": "MALE",
  "maritalStatus": "SINGLE",
  "ethnicity": "African",
  "idType": "NIDA",
  "idNumber": "19900515-12345-67890-12",
  "nameOnId": "John Doe",
  "idPhotoUrl": "https://storage.example.com/ids/john_id.jpg",
  "primaryAddress": "123 Main Street",
  "city": "Dar es Salaam",
  "country": "Tanzania",
  "region": "Dar es Salaam",
  "district": "Kinondoni",
  "zipCode": "12345",
  "ownsBusiness": true,
  "hasBusinessLicense": true,
  "businessName": "JD Tech Solutions",
  "businessEmail": "info@jdtech.com",
  "businessPhoneNumber": "+255712345679",
  "businessTinNumber": "123-456-789",
  "businessIndustry": "TECHNOLOGY",
  "businessWebsite": "https://jdtech.com",
  "businessAddress": "456 Business Avenue",
  "businessLicenseCertificateUrl": "https://storage.example.com/licenses/business_license.pdf",
  "businessTinCertificateUrl": "https://storage.example.com/certificates/tin.pdf",
  "loanApplicationLetterUrl": "https://storage.example.com/letters/loan_application.pdf",
  "boardResolutionUrl": "https://storage.example.com/resolutions/board_resolution.pdf",
  "businessLicenseEvidenceUrl": "https://storage.example.com/evidence/license_evidence.pdf",
  "taxClearanceCertificateUrl": "https://storage.example.com/certificates/tax_clearance.pdf",
  "taxpayerTin": "987-654-321",
  "taxpayerIdType": "NIDA",
  "taxpayerIdNumber": "19900515-12345-67890-12",
  "taxpayerNameOnId": "John Doe",
  "certificateOfRegistrationUrl": "https://storage.example.com/certificates/registration.pdf",
  "bankStatementUrl": "https://storage.example.com/statements/bank_statement.pdf",
  "allPurposeSupportingDocsUrl": "https://storage.example.com/docs/supporting_docs.pdf",
  "brelaSearchReturnsUrl": "https://storage.example.com/brela/search_returns.pdf",
  "callNotes": "Applying for business expansion loan"
}

Request Body Parameters:

Parameter Type Required Description Validation
whoIsApplying string No Who is submitting the application enum: MYSELF, SOMEONE_ELSE
fullName string No Full legal name of the applicant Max: 200 characters
username string No Username of the applicant Max: 100 characters
email string No Email address Must be valid email format
phoneNumber string No Phone number with country code Max: 20 characters
countryCode string No International dialing code Max: 10 characters
nationality string No Nationality of the applicant Max: 100 characters
preferredContactMethod string No Preferred way to be contacted enum: EMAIL, SMS, PHONE_CALL
profilePictureUrl string No URL to profile picture Valid URL format
employmentStatus string No Current employment situation enum: EMPLOYED, SELF_EMPLOYED, UNEMPLOYED, STUDENT, RETIRED
employerName string No Name of current employer Max: 200 characters
jobTitle string No Current job title Max: 200 characters
employmentType string No Type of employment enum: FULL_TIME, PART_TIME, CONTRACT, FREELANCE, INTERNSHIP
dateOfBirth date No Date of birth ISO 8601 date format (YYYY-MM-DD)
placeOfBirth string No Place where applicant was born Max: 200 characters
sex string No Biological sex enum: MALE, FEMALE, OTHER, PREFER_NOT_TO_SAY
maritalStatus string No Current marital status enum: SINGLE, MARRIED, DIVORCED, WIDOWED, SEPARATED
ethnicity string No Ethnic background Max: 100 characters
idType string No Type of identification document enum: NATIONAL_ID, PASSPORT, DRIVERS_LICENSE, VOTERS_ID, NIDA
idNumber string No Identification document number Max: 100 characters
nameOnId string No Name as it appears on ID Max: 200 characters
idPhotoUrl string No URL to ID document photo Valid URL format
primaryAddress string No Primary residential address Max: 500 characters
city string No City of residence Max: 100 characters
country string No Country of residence Max: 100 characters
region string No Region/State of residence Max: 100 characters
district string No District of residence Max: 100 characters
zipCode string No Postal/ZIP code Max: 20 characters
ownsBusiness boolean No Whether applicant owns a business true or false
hasBusinessLicense boolean No Whether business has a valid license true or false
businessName string No Registered business name Max: 200 characters
businessEmail string No Business email address Must be valid email format
businessPhoneNumber string No Business contact number Max: 20 characters
businessTinNumber string No Business Tax Identification Number Max: 100 characters
businessIndustry string No Industry/sector of business enum: AGRICULTURE, MANUFACTURING, RETAIL, TECHNOLOGY, HEALTHCARE, EDUCATION, FINANCE, CONSTRUCTION, HOSPITALITY, TRANSPORTATION, REAL_ESTATE, PROFESSIONAL_SERVICES, ENTERTAINMENT, MARKETING, OTHER
businessWebsite string No Business website URL Valid URL format
businessAddress string No Physical business address Max: 500 characters
businessLicenseCertificateUrl string No URL to business license document Valid URL format
businessTinCertificateUrl string No URL to TIN certificate Valid URL format
loanApplicationLetterUrl string No URL to loan application letter Valid URL format
boardResolutionUrl string No URL to board resolution document Valid URL format
businessLicenseEvidenceUrl string No URL to business license evidence Valid URL format
taxClearanceCertificateUrl string No URL to tax clearance certificate Valid URL format
taxpayerTin string No Personal Tax Identification Number Max: 100 characters
taxpayerIdType string No Type of taxpayer ID enum: NATIONAL_ID, PASSPORT, DRIVERS_LICENSE, VOTERS_ID, NIDA
taxpayerIdNumber string No Taxpayer ID number Max: 100 characters
taxpayerNameOnId string No Name as appears on taxpayer ID Max: 200 characters
certificateOfRegistrationUrl string No URL to certificate of registration Valid URL format
bankStatementUrl string No URL to bank statement Valid URL format
allPurposeSupportingDocsUrl string No URL to general supporting documents Valid URL format
brelaSearchReturnsUrl string No URL to BRELA search returns Valid URL format
llcFundApplicationLetterUrl string No URL to LLC fund application letter Valid URL format
llcMemartUrl string No URL to LLC MEMART document Valid URL format
llcCertificateOfIncorporationUrl string No URL to LLC certificate of incorporation Valid URL format
partnershipDeedUrl string No URL to partnership deed Valid URL format
partnershipCertificateRegistrationUrl string No URL to partnership certificate Valid URL format
partnershipMemartUrl string No URL to partnership MEMART Valid URL format
partnershipCertificateIncorporationUrl string No URL to partnership incorporation cert Valid URL format
generalBrelaSearchUrl string No URL to general BRELA search Valid URL format
generalFundApplicationUrl string No URL to general fund application Valid URL format
generalMemartUrl string No URL to general MEMART Valid URL format
generalCertificateIncorporationUrl string No URL to general certificate of incorporation Valid URL format
callNotes string No Additional notes about the application Max: 5000 characters

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Draft saved successfully",
  "action_time": "2026-02-11T10:35:20",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "applicationId": "660e8400-e29b-41d4-a716-446655440001",
    "callId": "770e8400-e29b-41d4-a716-446655440002",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "whoIsApplying": "MYSELF",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+255712345678",
    "applicationStatus": "DRAFT",
    "createdAt": "2026-02-11T10:30:45",
    "updatedAt": "2026-02-11T10:35:20"
  }
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not found",
  "action_time": "2026-02-11T10:35:20",
  "data": "Form not found"
}

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Not authorized",
  "action_time": "2026-02-11T10:35:20",
  "data": "Not authorized"
}

3. Submit Application Form

Purpose: Submit a draft form for review (changes status from DRAFT to SUBMITTED)

Endpoint: POST {base_url}/useless-forms/applications/{applicationId}/submit

Access Level: 🔒 Protected (Requires Bearer Token - Must be the form owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
applicationId UUID Yes Unique identifier of the call application Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form submitted successfully",
  "action_time": "2026-02-11T11:00:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "applicationId": "660e8400-e29b-41d4-a716-446655440001",
    "callId": "770e8400-e29b-41d4-a716-446655440002",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "applicationStatus": "SUBMITTED",
    "submittedAt": "2026-02-11T11:00:00",
    "createdAt": "2026-02-11T10:30:45",
    "updatedAt": "2026-02-11T11:00:00"
  }
}

Success Response Fields:

Field Description
submittedAt Timestamp when the form was submitted
applicationStatus Changed to SUBMITTED status

Error Response Examples:

Bad Request (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Form already submitted",
  "action_time": "2026-02-11T11:00:00",
  "data": "Form already submitted"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not found",
  "action_time": "2026-02-11T11:00:00",
  "data": "Form not found"
}

4. Get Form by Application ID

Purpose: Retrieve a specific form using the application ID

Endpoint: GET {base_url}/useless-forms/applications/{applicationId}

Access Level: 🔒 Protected (Requires Bearer Token - Must be form owner or call owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
applicationId UUID Yes Unique identifier of the call application Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form retrieved successfully",
  "action_time": "2026-02-11T11:15:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "applicationId": "660e8400-e29b-41d4-a716-446655440001",
    "callId": "770e8400-e29b-41d4-a716-446655440002",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "whoIsApplying": "MYSELF",
    "fullName": "John Doe",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "phoneNumber": "+255712345678",
    "countryCode": "+255",
    "nationality": "Tanzanian",
    "preferredContactMethod": "EMAIL",
    "profilePictureUrl": "https://storage.example.com/profiles/john.jpg",
    "employmentStatus": "EMPLOYED",
    "employerName": "Tech Solutions Ltd",
    "jobTitle": "Software Engineer",
    "employmentType": "FULL_TIME",
    "dateOfBirth": "1990-05-15",
    "placeOfBirth": "Dar es Salaam",
    "sex": "MALE",
    "maritalStatus": "SINGLE",
    "ethnicity": "African",
    "idType": "NIDA",
    "idNumber": "19900515-12345-67890-12",
    "nameOnId": "John Doe",
    "idPhotoUrl": "https://storage.example.com/ids/john_id.jpg",
    "primaryAddress": "123 Main Street",
    "city": "Dar es Salaam",
    "country": "Tanzania",
    "region": "Dar es Salaam",
    "district": "Kinondoni",
    "zipCode": "12345",
    "ownsBusiness": true,
    "hasBusinessLicense": true,
    "businessName": "JD Tech Solutions",
    "businessEmail": "info@jdtech.com",
    "businessPhoneNumber": "+255712345679",
    "businessTinNumber": "123-456-789",
    "businessIndustry": "TECHNOLOGY",
    "businessWebsite": "https://jdtech.com",
    "businessAddress": "456 Business Avenue",
    "applicationStatus": "SUBMITTED",
    "submittedAt": "2026-02-11T11:00:00",
    "createdAt": "2026-02-11T10:30:45",
    "updatedAt": "2026-02-11T11:00:00"
  }
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not found",
  "action_time": "2026-02-11T11:15:00",
  "data": "Form not found"
}

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Not authorized",
  "action_time": "2026-02-11T11:15:00",
  "data": "Not authorized"
}

5. Get Form by Form ID

Purpose: Retrieve a specific form using the form's unique ID

Endpoint: GET {base_url}/useless-forms/{formId}

Access Level: 🔒 Protected (Requires Bearer Token - Must be form owner or call owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
formId UUID Yes Unique identifier of the form Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form retrieved successfully",
  "action_time": "2026-02-11T11:20:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "applicationId": "660e8400-e29b-41d4-a716-446655440001",
    "callId": "770e8400-e29b-41d4-a716-446655440002",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "applicationStatus": "SUBMITTED",
    "submittedAt": "2026-02-11T11:00:00",
    "createdAt": "2026-02-11T10:30:45",
    "updatedAt": "2026-02-11T11:00:00"
  }
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not found",
  "action_time": "2026-02-11T11:20:00",
  "data": "Form not found"
}

6. Get All Forms for a Call

Purpose: Retrieve all application forms submitted for a specific call with optional status filtering

Endpoint: GET {base_url}/useless-forms/calls/{callId}/forms

Access Level: 🔒 Protected (Requires Bearer Token - Must be call owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
callId UUID Yes Unique identifier of the call Must be valid UUID format

Query Parameters:

Parameter Type Required Description Validation Default
status string No Filter forms by application status enum: DRAFT, SUBMITTED, UNDER_REVIEW, APPROVED, REJECTED, WITHDRAWN null (all statuses)
page integer No Page number for pagination Min: 1 1
size integer No Number of items per page Min: 1, Max: 100 20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Forms retrieved successfully",
  "action_time": "2026-02-11T11:25:00",
  "data": {
    "content": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "applicationId": "660e8400-e29b-41d4-a716-446655440001",
        "callId": "770e8400-e29b-41d4-a716-446655440002",
        "callTitle": "SME Business Loan 2026",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "applicationStatus": "SUBMITTED",
        "submittedAt": "2026-02-11T11:00:00",
        "createdAt": "2026-02-11T10:30:45"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440004",
        "applicationId": "660e8400-e29b-41d4-a716-446655440005",
        "callId": "770e8400-e29b-41d4-a716-446655440002",
        "callTitle": "SME Business Loan 2026",
        "fullName": "Jane Smith",
        "email": "jane.smith@example.com",
        "applicationStatus": "APPROVED",
        "submittedAt": "2026-02-10T14:30:00",
        "createdAt": "2026-02-10T09:15:00"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalElements": 2,
    "totalPages": 1,
    "last": true,
    "size": 20,
    "number": 0,
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "numberOfElements": 2,
    "first": true,
    "empty": false
  }
}

Success Response Fields:

Field Description
content Array of form summaries
content[].id Unique identifier of the form
content[].applicationId Reference to the call application
content[].callId Reference to the call
content[].callTitle Title of the call
content[].fullName Applicant's full name
content[].email Applicant's email
content[].applicationStatus Current status of the application
content[].submittedAt When the form was submitted
content[].createdAt When the form was created
totalElements Total number of forms across all pages
totalPages Total number of pages
size Number of items per page
number Current page number (0-indexed)
first Whether this is the first page
last Whether this is the last page

7. Get My Forms

Purpose: Retrieve all forms created by the authenticated user

Endpoint: GET {base_url}/useless-forms/my-forms

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Query Parameters:

Parameter Type Required Description Validation Default
page integer No Page number for pagination Min: 1 1
size integer No Number of items per page Min: 1, Max: 100 20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Your forms retrieved successfully",
  "action_time": "2026-02-11T11:30:00",
  "data": {
    "content": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "applicationId": "660e8400-e29b-41d4-a716-446655440001",
        "callId": "770e8400-e29b-41d4-a716-446655440002",
        "callTitle": "SME Business Loan 2026",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "applicationStatus": "SUBMITTED",
        "submittedAt": "2026-02-11T11:00:00",
        "createdAt": "2026-02-11T10:30:45"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440006",
        "applicationId": "660e8400-e29b-41d4-a716-446655440007",
        "callId": "770e8400-e29b-41d4-a716-446655440008",
        "callTitle": "Youth Startup Grant 2026",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "applicationStatus": "DRAFT",
        "submittedAt": null,
        "createdAt": "2026-02-09T08:20:00"
      }
    ],
    "totalElements": 2,
    "totalPages": 1,
    "size": 20,
    "number": 0,
    "first": true,
    "last": true,
    "empty": false
  }
}

8. Review Application Form

Purpose: Review and update the status of a submitted form (approve, reject, etc.)

Endpoint: POST {base_url}/useless-forms/{formId}/review

Access Level: 🔒 Protected (Requires Bearer Token - Must be call owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
formId UUID Yes Unique identifier of the form to review Must be valid UUID format

Query Parameters:

Parameter Type Required Description Validation Default
status string Yes New status for the application enum: SUBMITTED, UNDER_REVIEW, APPROVED, REJECTED, WITHDRAWN null
notes string No Review notes or feedback for the applicant Max: 5000 characters null

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form reviewed successfully",
  "action_time": "2026-02-11T11:45:00",
  "data": null
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not found",
  "action_time": "2026-02-11T11:45:00",
  "data": "Form not found"
}

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Not authorized",
  "action_time": "2026-02-11T11:45:00",
  "data": "Not authorized"
}

9. Get Form Statistics for Call

Purpose: Get aggregated statistics of forms by status for a specific call

Endpoint: GET {base_url}/useless-forms/calls/{callId}/stats

Access Level: 🔒 Protected (Requires Bearer Token - Must be call owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
callId UUID Yes Unique identifier of the call Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Stats retrieved successfully",
  "action_time": "2026-02-11T11:50:00",
  "data": {
    "submitted": 45,
    "approved": 12,
    "rejected": 8,
    "draft": 23,
    "total": 88
  }
}

Success Response Fields:

Field Description
submitted Number of forms in SUBMITTED status
approved Number of forms in APPROVED status
rejected Number of forms in REJECTED status
draft Number of forms in DRAFT status
total Total number of all forms for this call

10. Get User's Form for Specific Call

Purpose: Retrieve a specific user's form for a particular call

Endpoint: GET {base_url}/useless-forms/calls/{callId}/users/{userId}

Access Level: 🔒 Protected (Requires Bearer Token - Must be the user themselves or call owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
callId UUID Yes Unique identifier of the call Must be valid UUID format
userId UUID Yes Unique identifier of the user Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form retrieved successfully",
  "action_time": "2026-02-11T12:00:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "applicationId": "660e8400-e29b-41d4-a716-446655440001",
    "callId": "770e8400-e29b-41d4-a716-446655440002",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "applicationStatus": "APPROVED",
    "submittedAt": "2026-02-11T11:00:00",
    "createdAt": "2026-02-11T10:30:45",
    "updatedAt": "2026-02-11T11:45:00"
  }
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not found",
  "action_time": "2026-02-11T12:00:00",
  "data": "Form not found"
}

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Cannot view form at this stage",
  "action_time": "2026-02-11T12:00:00",
  "data": "Cannot view form at this stage"
}

11. Get Total Applicants Count

Purpose: Get the total number of applicants for a specific call

Endpoint: GET {base_url}/useless-forms/calls/{callId}/applicants/count

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
callId UUID Yes Unique identifier of the call Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Applicant count retrieved successfully",
  "action_time": "2026-02-11T12:05:00",
  "data": {
    "totalApplicants": 88
  }
}

Success Response Fields:

Field Description
totalApplicants Total number of unique applicants for this call

12. Get My Status in Call

Purpose: Get the authenticated user's application status for a specific call

Endpoint: GET {base_url}/useless-forms/calls/{callId}/my-status

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
callId UUID Yes Unique identifier of the call Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Your status retrieved successfully",
  "action_time": "2026-02-11T12:10:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "applicationId": "660e8400-e29b-41d4-a716-446655440001",
    "callId": "770e8400-e29b-41d4-a716-446655440002",
    "userId": "880e8400-e29b-41d4-a716-446655440003",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "applicationStatus": "UNDER_REVIEW",
    "submittedAt": "2026-02-11T11:00:00",
    "createdAt": "2026-02-11T10:30:45",
    "updatedAt": "2026-02-11T11:45:00"
  }
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "You have not applied to this call",
  "action_time": "2026-02-11T12:10:00",
  "data": "You have not applied to this call"
}

13. Check If User Has Applied

Purpose: Check whether the authenticated user has already applied to a specific call

Endpoint: GET {base_url}/useless-forms/calls/{callId}/check-applied

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
callId UUID Yes Unique identifier of the call Must be valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Check completed",
  "action_time": "2026-02-11T12:15:00",
  "data": {
    "hasApplied": true
  }
}

Success Response Fields:

Field Description
hasApplied Boolean indicating whether the user has applied (true) or not (false)

14. Get Applicants for Call (With Filters)

Purpose: Retrieve a paginated list of applicants for a specific call with optional filtering by status and search term

Endpoint: GET {base_url}/useless-forms/calls/{callId}/applicants

Access Level: 🔒 Protected (Requires Bearer Token - Must be call owner)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
callId UUID Yes Unique identifier of the call Must be valid UUID format

Query Parameters:

Parameter Type Required Description Validation Default
status string No Filter applicants by application status enum: DRAFT, SUBMITTED, UNDER_REVIEW, APPROVED, REJECTED, WITHDRAWN null (all statuses)
search string No Search term to filter by name, email, or phone number Max: 200 characters null
page integer No Page number for pagination Min: 1 1
size integer No Number of items per page Min: 1, Max: 100 20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Applicants retrieved successfully",
  "action_time": "2026-02-11T12:20:00",
  "data": {
    "content": [
      {
        "userId": "880e8400-e29b-41d4-a716-446655440003",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "phoneNumber": "+255712345678",
        "applicationStatus": "SUBMITTED",
        "submittedAt": "2026-02-11T11:00:00",
        "createdAt": "2026-02-11T10:30:45"
      },
      {
        "userId": "880e8400-e29b-41d4-a716-446655440009",
        "fullName": "Jane Smith",
        "email": "jane.smith@example.com",
        "phoneNumber": "+255723456789",
        "applicationStatus": "APPROVED",
        "submittedAt": "2026-02-10T14:30:00",
        "createdAt": "2026-02-10T09:15:00"
      }
    ],
    "totalElements": 45,
    "totalPages": 3,
    "size": 20,
    "number": 0,
    "first": true,
    "last": false,
    "empty": false
  }
}

Success Response Fields:

Field Description
content Array of applicant summaries
content[].userId Unique identifier of the user/applicant
content[].fullName Applicant's full name
content[].email Applicant's email address
content[].phoneNumber Applicant's phone number
content[].applicationStatus Current status of the application
content[].submittedAt When the application was submitted
content[].createdAt When the application was created
totalElements Total number of applicants across all pages
totalPages Total number of pages
size Number of items per page
number Current page number (0-indexed)
first Whether this is the first page
last Whether this is the last page

Error Response Examples:

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Not authorized to view applicants for this call",
  "action_time": "2026-02-11T12:20:00",
  "data": "Not authorized to view applicants for this call"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Call not found",
  "action_time": "2026-02-11T12:20:00",
  "data": "Call not found"
}

Quick Reference Guide

Application Status Flow

DRAFT → SUBMITTED → UNDER_REVIEW → APPROVED/REJECTED
                                  ↘ WITHDRAWN (optional)

Status Descriptions

  • DRAFT: Form is being filled out, can be edited multiple times
  • SUBMITTED: Form has been submitted for review, cannot be edited
  • UNDER_REVIEW: Call owner is actively reviewing the application
  • APPROVED: Application has been approved
  • REJECTED: Application has been rejected
  • WITHDRAWN: Applicant has withdrawn their application

Authorization Rules

Role Can Start Form Can Save Draft Can Submit Can Review Can View All Forms
Applicant (Form Owner) ✅ ✅ ✅ ❌ ❌
Call Owner ❌ ❌ ❌ ✅ ✅
Other Users ❌ ❌ ❌ ❌ ❌

Common Use Cases

Use Case 1: User Applies to a Call

  1. POST /applications/{applicationId}/start - Start form
  2. PUT /applications/{applicationId}/draft - Save progress (can repeat)
  3. POST /applications/{applicationId}/submit - Submit form

Use Case 2: User Checks Their Application Status

  1. GET /calls/{callId}/check-applied - Check if already applied
  2. GET /calls/{callId}/my-status - View current status

Use Case 3: Call Owner Reviews Applications

  1. GET /calls/{callId}/applicants?status=SUBMITTED - Get submitted applications
  2. GET /calls/{callId}/users/{userId} - View specific application
  3. POST /{formId}/review?status=APPROVED&notes=Great candidate - Approve/Reject

Use Case 4: Call Owner Views Statistics

  1. GET /calls/{callId}/stats - View aggregated statistics
  2. GET /calls/{callId}/applicants/count - Get total applicant count

Pagination Best Practices

  • Default page size is 20, maximum is 100
  • Page numbers start from 1
  • Use totalPages and last to determine if more pages exist
  • Consider the response payload size when setting page size

Common HTTP Status Codes

  • 200 OK: Successful GET/PUT/POST request
  • 400 Bad Request: Invalid request data or form already submitted
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Insufficient permissions or not authorized
  • 404 Not Found: Resource not found (form, call, or user)
  • 500 Internal Server Error: Unexpected server error

Data Format Standards

  • Dates: Use ISO 8601 format (YYYY-MM-DD) for date fields
  • Timestamps: Use ISO 8601 format with timezone (2026-02-11T10:30:45)
  • UUIDs: Standard UUID v4 format (550e8400-e29b-41d4-a716-446655440000)
  • Phone Numbers: Include country code (e.g., +255712345678)
  • URLs: Must be valid HTTP/HTTPS URLs for document storage

Additional Notes

Document Upload Strategy

  • The API stores URLs to documents, not the documents themselves
  • Files should be uploaded to a separate file storage service (e.g., AWS S3, Azure Blob Storage)
  • After upload, include the returned URL in the form draft
  • Supported document types: Business licenses, tax certificates, ID photos, bank statements, etc.

Form Validation

  • All fields are optional in draft mode to allow progressive completion
  • Validation occurs on the client side before submission
  • Call owners may define required fields based on call requirements

Performance Considerations

  • Use pagination for large result sets
  • Filter by status to reduce payload size
  • Consider implementing caching for frequently accessed data
  • Use search parameters to narrow down results

Security Notes

  • All endpoints require authentication except where explicitly noted
  • Users can only access their own forms unless they are the call owner
  • Call owners have read-only access to submitted forms
  • Sensitive data (ID numbers, financial info) should be encrypted at rest
  • Implement rate limiting to prevent abuse

End of Documentation

For questions or support, please contact the FursaHub Backend Team.

No comments to display

Back to top