Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/harshalw2003/BidAuc/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through the complete BidAuc workflow — from creating an account with OTP-based phone verification, to posting a job as a Seeker, and submitting a bid as a Provider. By the end you will have made real API calls and understand how both sides of the marketplace interact.
All BidAuc API endpoints run on http://localhost:5000. Authentication uses httpOnly cookies issued after OTP login, so include -c / -b flags in your curl calls or configure your HTTP client to send cookies automatically.

​
Seeker flow: post a job

1

Generate an OTP

Request a one-time password for your phone number. Send the 10-digit number as a string.
curl --request POST \
  --url http://localhost:5000/user/generateOtp \
  --header 'Content-Type: application/json' \
  --data '{
    "phoneNumber": "9876543210"
  }'
A successful response confirms the OTP was generated:
{
  "message": "OTP Sent successfully",
  "success": true
}
In development, Twilio SMS delivery is disabled. The OTP is always 123456 regardless of the phone number.
2

Register as a Seeker

Submit the OTP alongside your profile details. Set "role" to "Seeker" to create a job-poster account. Name fields are nested under userName.
curl --request POST \
  --url http://localhost:5000/user/register \
  --header 'Content-Type: application/json' \
  -c cookies.txt \
  --data '{
    "phoneNumber": "9876543210",
    "otp": "123456",
    "role": "Seeker",
    "email": "alex@example.com",
    "userName": {
      "firstName": "Alex",
      "lastName": "Rivera"
    }
  }'
The server sets a JWT in an httpOnly cookie named token and returns a confirmation:
{
  "message": "User Registered Successfully!!",
  "success": true,
  "jwtToken": "<jwt>"
}
The JWT cookie is saved in cookies.txt. Reuse it with -b cookies.txt for all subsequent requests in this guide.
3

Post your first job

With your Seeker session active, create a job. Send as multipart/form-data. The category value must exactly match one of the 22 valid category names (e.g. "Plumbing").
curl --request POST \
  --url http://localhost:5000/job/create \
  -b cookies.txt \
  -F "jobName=Fix leaking kitchen faucet" \
  -F "category=Plumbing" \
  -F "urgency=High" \
  -F "description=The kitchen faucet drips constantly. Need a licensed plumber to replace the washers and check the supply line." \
  -F "additionalRequirements=Must bring own tools"

{
  "success": true,
  "message": "Job posted successfully!"
}
Your job is now live and visible to Providers browsing the marketplace with bidStatus: "unaccepted" and completionStatus: "pending".

​
Provider flow: place a bid

1

Register as a Provider

Open a new terminal (or use a fresh cookie jar) and register a second account with "role": "Provider". Providers can include a businessName in their profile later via POST /user/updatePersonalDetails.
curl --request POST \
  --url http://localhost:5000/user/generateOtp \
  --header 'Content-Type: application/json' \
  --data '{ "phoneNumber": "9876500001" }'

curl --request POST \
  --url http://localhost:5000/user/register \
  --header 'Content-Type: application/json' \
  -c provider-cookies.txt \
  --data '{
    "phoneNumber": "9876500001",
    "otp": "123456",
    "role": "Provider",
    "email": "jordan@example.com",
    "userName": {
      "firstName": "Jordan",
      "lastName": "Kim"
    }
  }'
2

Browse available jobs

As a Provider, list all pending jobs to find one to bid on.
curl --request GET \
  --url http://localhost:5000/job/getAllJobs \
  -b provider-cookies.txt
The response returns an array of jobs where completionStatus: "pending". Note the _id of the job you want to bid on.
3

Submit a bid

Post a bid with your offered price and a description of how you will approach the work. Pass the job’s _id as jobId.
curl --request POST \
  --url http://localhost:5000/bid/post \
  --header 'Content-Type: application/json' \
  -b provider-cookies.txt \
  --data '{
    "jobId": "664c3d...",
    "offerPrice": 85,
    "description": "I will replace the washers, inspect the supply line, and test for leaks. Parts and labour included."
  }'

{
  "success": true,
  "message": "Bid Posted Successfully",
  "bid": {
    "_id": "664d4e...",
    "job": "664c3d...",
    "offerPrice": 85,
    "status": "unaccepted",
    "timePosted": "2026-05-25T10:15:00.000Z"
  }
}
4

Seeker accepts the bid

Switch back to your Seeker session. Accept the bid by passing the bid’s _id as bidId.
curl --request POST \
  --url http://localhost:5000/bid/acceptedBids \
  --header 'Content-Type: application/json' \
  -b cookies.txt \
  --data '{
    "bidId": "664d4e..."
  }'

{
  "success": true,
  "message": "Bid successfully accepted",
  "bid": { "_id": "664d4e...", "status": "accepted" }
}
Accepting a bid sets job.bidStatus to "accepted" and assigns the winning Provider on the job document.
Once a bid is accepted, no further bids can be accepted for the same job.

​
What’s next

Core concepts

Understand Seeker and Provider roles, permissions, and how the dual-role model shapes every API call.

API reference

Full reference for every endpoint, including request parameters, response shapes, and error codes.

Build docs developers (and LLMs) love

Get started for freeTalk to us