API Documentation

Integrate with our platform using the REST API

Authentication

All API requests require a Bearer token. Generate an API key from Settings > Integrations.

curl -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  https://your-domain.com/api/v1/tenders

Rate Limiting

API calls are limited based on your subscription plan. Pro: 1,000/day, Enterprise: Unlimited.

Pagination

All list endpoints return paginated responses with the following structure:

{
  "data": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

Endpoints

GET/api/v1/tenders

List tenders with pagination and filtering

Required scope: tenders.read

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`page_size`	number	No	Items per page (max: 100)
`source`	string	No	Filter by source (etimad, nupco)
`agency`	string	No	Filter by agency name

GET/api/v1/tenders/:id

Get tender details with line items

Required scope: tenders.read

Parameter	Type	Required	Description
`id`	number	Yes	Tender ID

GET/api/v1/search

Search tenders by keyword (including item names)

Required scope: search

Parameter	Type	Required	Description
`q`	string	No	Search query
`source`	string	No	Filter by source
`agency`	string	No	Filter by agency
`type`	string	No	Filter by tender type
`date_from`	string	No	Start date (ISO)
`date_to`	string	No	End date (ISO)
`page`	number	No	Page number
`page_size`	number	No	Items per page

GET/api/v1/bids

List your organization's bids

Required scope: bids.read

Parameter	Type	Required	Description
`status`	string	No	Filter by status
`page`	number	No	Page number
`page_size`	number	No	Items per page

GET/api/v1/favorites

List your organization's favorite tenders

Required scope: favorites.read

Parameter	Type	Required	Description
`page`	number	No	Page number
`page_size`	number	No	Items per page

Webhooks

Receive real-time notifications when events occur. Configure webhooks from Settings > Integrations.

Available Events

tender.matched — New tender matches your alerts or products
bid.status_changed — Bid status has changed
deadline.approaching — Tender deadline is approaching

Signature Verification

All webhook payloads are signed with HMAC-SHA256. Verify the X-Webhook-Signature header:

// Verify webhook signature
const crypto = require('crypto');
const signature = req.headers['x-webhook-signature'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature === expected) {
  // Valid webhook
}