Skip to main content
Contracts are the central record binding a client, a freelancer, and a job together. Once a payment is completed via Stripe, a contract is created. The contract moves through a defined status lifecycle before funds are released from escrow.
Contract creation is triggered after a successful Stripe payment. See Payments endpoints for the payment initiation flow.

​
Contract status lifecycle

StatusDescription
PendingContract created, waiting for freelancer approval
StartedFreelancer approved the contract
OngoingWork is in progress
CompletedWork is complete and fund release has been approved
CanceledContract was canceled by either party

​
POST /api/client/create-contract/:jobId

Create a contract for a job after payment has been processed. The authenticated client’s ID is taken from the JWT. Auth required: Yes — client role

​
Path parameters

​
jobId
string
required
MongoDB ObjectId of the job this contract is for.

​
Request body

​
freelancerId
string
required
MongoDB ObjectId of the freelancer being hired.
​
amount
number
required
Contract value in INR. Should match the rate of the job.

​
Response

​
message
string
Confirmation that the contract was created.
​
contract
object
The newly created contract document.
cURL
curl -X POST https://your-backend-domain.com/api/client/create-contract/64f1a2b3c4d5e6f7a8b9c0d4 \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "freelancerId": "64f1a2b3c4d5e6f7a8b9c0d6",
    "amount": 50000
  }'

​
DELETE /api/client/cancel-contract/:contractId

Cancel a contract. Both the client and the freelancer can initiate cancellation. Canceling a contract while escrow is funded will trigger the refund flow. Auth required: Yes — client or freelancer role

​
Path parameters

​
contractId
string
required
MongoDB ObjectId of the contract to cancel.

​
Response

​
message
string
Confirmation that the contract was canceled.
Canceling a funded contract does not automatically process a refund. An admin must approve the refund via PUT /api/admin/escrow/refund-client/:contractId/:clientId. See Payments endpoints for the full refund flow.
cURL
curl -X DELETE https://your-backend-domain.com/api/client/cancel-contract/64f1a2b3c4d5e6f7a8b9c0ef \
  -H "Authorization: Bearer <accessToken>"

​
GET /api/client/is-created/:jobId/:clientId

Check whether a contract already exists for a given job and client. Use this to prevent duplicate contract creation. Auth required: No

​
Path parameters

​
jobId
string
required
MongoDB ObjectId of the job.
​
clientId
string
required
MongoDB ObjectId of the client.

​
Response

​
contract
object
The existing contract document if one exists, or null if no contract has been created yet.
cURL
curl "https://your-backend-domain.com/api/client/is-created/64f1a2b3c4d5e6f7a8b9c0d4/64f1a2b3c4d5e6f7a8b9c0d5"

​
GET /api/client/get-contracts/:clientId

Retrieve all contracts belonging to a specific client. Auth required: No

​
Path parameters

​
clientId
string
required
MongoDB ObjectId of the client.

​
Response

​
count
number
Total number of contracts returned.
​
data
object[]
Array of contract documents with populated jobId, freelancerId, and clientId references.
cURL
curl "https://your-backend-domain.com/api/client/get-contracts/64f1a2b3c4d5e6f7a8b9c0d5"

​
GET /api/client/all-contracts

Return all contracts across all users. Intended for admin dashboards and oversight tooling. Auth required: No (no middleware applied, but intended for admin use)
This endpoint does not enforce authentication at the route level. You should restrict access to it at the infrastructure or proxy layer in production deployments.

​
Response

​
data
object[]
Array of all contract documents across the platform.
cURL
curl "https://your-backend-domain.com/api/client/all-contracts"

​
PATCH /api/client/release-fund/:contractId

Request that the escrowed funds be released to the freelancer. This sets releaseFundStatus to Requested. An admin must then approve the release via the escrow endpoints. Auth required: Yes — client role

​
Path parameters

​
contractId
string
required
MongoDB ObjectId of the contract.

​
Response

​
message
string
Confirmation that the fund release request was recorded.
Submitting a release request does not immediately transfer funds. The request enters a Requested state and must be approved by an admin through PUT /api/admin/escrow/release-fund/:contractId.
cURL
curl -X PATCH https://your-backend-domain.com/api/client/release-fund/64f1a2b3c4d5e6f7a8b9c0ef \
  -H "Authorization: Bearer <accessToken>"

​
POST /api/freelancer/contract/approve-contract/:contractId/:freelancerId

Freelancer accepts the contract, moving its status from Pending to Started. Auth required: Yes — freelancer role

​
Path parameters

​
contractId
string
required
MongoDB ObjectId of the contract.
​
freelancerId
string
required
MongoDB ObjectId of the freelancer approving the contract.

​
Response

Confirmation message and the updated contract document.
cURL
curl -X POST https://your-backend-domain.com/api/freelancer/contract/approve-contract/64f1a2b3c4d5e6f7a8b9c0ef/64f1a2b3c4d5e6f7a8b9c0d6 \
  -H "Authorization: Bearer <accessToken>"

​
GET /api/freelancer/contract/get-contracts/:freelancerId

Retrieve all contracts for a specific freelancer. Auth required: No

​
Path parameters

​
freelancerId
string
required
MongoDB ObjectId of the freelancer.

​
Response

Array of contract documents associated with the freelancer.
cURL
curl "https://your-backend-domain.com/api/freelancer/contract/get-contracts/64f1a2b3c4d5e6f7a8b9c0d6"

​
GET /api/freelancer/contract/view-contract/:contractId

Retrieve full details for a single contract including populated references. Auth required: No

​
Path parameters

​
contractId
string
required
MongoDB ObjectId of the contract.

​
Response

The full contract document with populated jobId, clientId, and freelancerId.
cURL
curl "https://your-backend-domain.com/api/freelancer/contract/view-contract/64f1a2b3c4d5e6f7a8b9c0ef"

​
PUT /api/freelancer/contract/update-status/:contractId

Update the working status of a contract (e.g., move from Started to Ongoing, or mark as Completed). Auth required: Yes — freelancer role

​
Path parameters

​
contractId
string
required
MongoDB ObjectId of the contract.

​
Request body

​
status
string
required
New status value. One of Started, Ongoing, Completed, or Canceled.

​
Response

The updated contract document.
cURL
curl -X PUT https://your-backend-domain.com/api/freelancer/contract/update-status/64f1a2b3c4d5e6f7a8b9c0ef \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"status": "Ongoing"}'

​
GET /api/freelancer/contract/completed-works/:freelancerId

Retrieve all contracts with status Completed for a given freelancer. Useful for portfolio and earnings history views. Auth required: No

​
Path parameters

​
freelancerId
string
required
MongoDB ObjectId of the freelancer.

​
Response

Array of completed contract documents.
cURL
curl "https://your-backend-domain.com/api/freelancer/contract/completed-works/64f1a2b3c4d5e6f7a8b9c0d6"

Build docs developers (and LLMs) love

Get started for freeTalk to us