The Saudi government issues more than 300,000 tenders a year on Etimad, its official electronic procurement platform. Most companies still track them manually — a spreadsheet, a daily login, someone assigned to check the portal. That approach fails when a tender closes while your team is in a meeting, when you need contract history to qualify a supplier, or when a bank requires verified salary data before approving a line of credit.
Etimad exposes an official API, and a growing ecosystem of third-party tools fills the gaps the official portal leaves open. This guide covers how to register, authenticate, and integrate programmatically — so your procurement process runs while your team focuses on bids, not browser tabs.
What Etimad Offers Developers
The Etimad Developer Portal at apiportal.etimad.sa hosts official API products for three primary use cases:
- Contracts Plus — Inquiry into existing and historical government contracts by supplier CR number, beneficiary ID, or 700 number. Used by banks and ERP systems to verify vendor track records before onboarding or financing.
- Salary Certificate — Retrieves a certified salary statement for government employees based on the latest processed payroll. Widely used in bank loan origination and Fintech products.
- Open Data — Aggregated, read-only government procurement data for analytics, dashboards, and reporting pipelines.
Pricing on the Contracts Plus API is tiered: from 45 SAR per inquiry for fewer than 10 queries a month down to 20 SAR per inquiry for volumes above 1,000. Pricing applies to both successful (HTTP 200) and failed (400, 404) responses — which makes input validation non-optional.
Registering on the Etimad Developer Portal
Access is gated behind an approval workflow. Individual developers and private-sector companies both qualify, but the steps start with your commercial registration:
- Log in to
apiportal.etimad.sausing your Etimad Business credentials — linked to your CR via Nafath. - Browse available API products and select the one that fits your integration use case.
- Submit a subscription request. Approval typically arrives within one to three business days.
- Once approved, create an application inside the portal — this generates your Client ID and Client Secret.
- Test against the sandbox environment using the pre-populated contract and salary data before switching to production.
Sandbox access lets you validate your full integration pipeline without incurring any per-query charges.
Authentication: Token-Based Access
Etimad uses the client credentials flow. You exchange your Client ID and Client Secret for a short-lived bearer token, then attach that token to every API request.
async function getEtimadToken(): Promise<string> {
const res = await fetch("https://publicapi.etimad.sa/token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientId: process.env.ETIMAD_CLIENT_ID,
clientSecret: process.env.ETIMAD_CLIENT_SECRET,
}),
});
if (!res.ok) throw new Error(`Token request failed: ${res.status}`);
const data = await res.json();
return data.access_token;
}Note: Exact endpoint URLs and token lifetime are documented in the Etimad Developer Portal's Swagger interface after subscription. Refresh tokens proactively — store the expiry timestamp alongside the token rather than waiting for a 401 to trigger a retry.
Querying Contract Data
Once authenticated, the Contracts Plus endpoint accepts a beneficiary identifier and returns historical contract details — agency names, contract values, dates, and completion status.
interface ContractRecord {
contractNumber: string;
agencyName: string;
agencyNameEn: string;
contractValue: number;
startDate: string;
endDate: string;
status: string;
}
async function getContractsByCR(
crNumber: string,
token: string
): Promise<ContractRecord[]> {
const res = await fetch(
`https://publicapi.etimad.sa/contracts/v1/inquiry` +
`?beneficiaryCR=${encodeURIComponent(crNumber)}&beneficiaryIdType=CR`,
{ headers: { Authorization: `Bearer ${token}` } }
);
if (!res.ok) throw new Error(`Contract query failed: ${res.status}`);
const data = await res.json();
return data.contracts ?? [];
}A supplier with 50 completed government contracts at full value is a fundamentally different risk from one with three partial completions. This data, once buried in PDFs and portal screenshots, is now a single API call.
Monitoring Tenders: The Missing Piece
The official Etimad Developer Portal does not expose a real-time tender API — it focuses on contract and financial data, not live procurement listings. Third-party services like Tenders Alerts fill this gap by aggregating from tenders.etimad.sa and exposing REST endpoints your system can poll.
A monitoring service typically runs on a schedule and pushes new matching tenders to Slack, your CRM, or a project management tool:
async function fetchNewTenders(apiKey: string, region?: string): Promise<void> {
const params = new URLSearchParams({ status: "open" });
if (region) params.set("region", region);
const res = await fetch(`https://api.tendersalerts.com/tenders?${params}`, {
headers: { "x-api-key": apiKey },
});
if (!res.ok) throw new Error(`Tender fetch failed: ${res.status}`);
const body = await res.json();
for (const tender of body.data ?? []) {
await notifyTeam(tender);
}
}The value of combining both layers: Etimad's official API gives you verified supplier and contract data; the third-party tenders layer gives you real-time deal flow. Together they cover the full procurement cycle without manual portal checks.
Four Failure Modes to Mitigate
The pattern we see repeatedly when integrating KSA government platforms — similar to WPS and NPHIES integrations — is that the data is available but the pipeline assumptions are wrong:
- Token expiry on long-running jobs. Don't rely on the API returning 401 to trigger a refresh. Store the token expiry time and refresh proactively before submitting a batch.
- Failed lookups billed at the same rate. Validate CR numbers and beneficiary IDs before submitting — malformed identifiers are charged the same as successful queries.
- Sandbox-to-production schema drift. Sandbox schemas occasionally lag behind production releases. Always validate your response parsing against at least a few real production responses before go-live.
- No pagination guard on large histories. Contract histories for established suppliers can span hundreds of records. Implement pagination from day one and set a sensible result cap to prevent memory pressure in your pipeline.
Wiring Etimad into Your ERP
The most common integration pattern for Saudi B2B companies connects three government platforms into a single procurement workflow:
- Etimad API for automatic supplier qualification: before onboarding any new vendor, pull their contract history and score their government track record programmatically.
- ZATCA (Fatoorah) for invoice matching: after a government contract is awarded, cross-reference purchase orders with e-invoicing data from ZATCA to close the payment loop without manual reconciliation.
- Qiwa / Nitaqat for workforce compliance: tenders above certain value thresholds require an active Nitaqat rating. A Qiwa integration check before bid submission prevents disqualification at the last stage.
The same automation logic that reduces overhead on internal workflows applies to procurement: fewer humans in the polling loop means fewer missed opportunities and faster bid turnaround.
Start Automating Your Government Procurement
Etimad has the API infrastructure in place. The gap is the integration layer — the TypeScript service, the webhook, the ERP connector that turns a government portal into a live data feed your systems can act on automatically.
If your company bids on Saudi government projects and still checks Etimad manually, that is a workflow problem we can solve. Talk to our integration team about building a custom Etimad connector for your stack — from supplier qualification to tender alerting to payment verification.