# Get your ZATCA and Fatoora records through an API

> Read the List of Solutions and Devices, your E-invoicing Statistics and the returns waiting under Returns with one API call each. Then have a workflow check every Monday which CSIDs expire within 30 days and email you those devices.

Page: https://fous.com/automate/zatca-e-services
Updated: 2026-11-12

Works with your own ZATCA e-Services account. Fous is an independent product.

## What you can build on the ZATCA portal

### List onboarded solutions and devices

Reads View List Of Solutions And Devices on the Fatoora portal: every onboarded EGS unit with its status and certificate dates.

- Takes: Status (optional), certificate expiry before (optional)
- Returns: Common name, serial number, VAT number, organization unit name, organization name, country, status, onboarding date, certificate expiry date, revocation date

### Get e-invoicing statistics

Reads E-invoicing Statistics on the Fatoora portal: documents sent for reporting and for clearance in the past 12 months, by outcome.

- Takes: Nothing
- Returns: For Reported and for Cleared: total, documents accepted, accepted with warnings, rejected

### List returns waiting to be filed

Clicks Returns in the side menu of login.zatca.gov.sa, selects the tax type and reads the returns listed for filing.

- Takes: Tax type, such as VAT
- Returns: Return name, period, status

### Request a Zakat certificate

On the Zakat tab, opens Request for certificate, selects New Request, fills in the form and submits it.

- Takes: The certificate form's fields, as you give them
- Returns: Whether the request went through, certificate details shown

## Automate the ZATCA portal with a workflow

A [workflow](/product/workflows) runs your methods as one process, with nobody at the screen. A schedule or a call from your own system starts it, the steps run in order, and the result arrives in your inbox or in the systems you already use.

### CSIDs that expire within 30 days

Starts: Every Monday at 8:00, Riyadh time

1. List the onboarded solutions and devices with status Active.
2. Keep the devices whose certificate expiry date is within the next 30 days.
3. Email you the list with common name, serial number, organization unit name and expiry date.

### Rejected e-invoice counts, posted when they change

Starts: Every weekday at 9:00, Riyadh time

1. Get the E-invoicing Statistics for Reported and Cleared.
2. Keep the result only when the rejected count changed since the last run.
3. Post the new counts for accepted, accepted with warnings and rejected to your webhook.

### VAT returns open for filing, every month

Starts: On the 1st of every month at 9:00, Riyadh time

1. List the returns under Returns for VAT.
2. Keep the returns that were not there on the last run.
3. Email you each one with its period and status.

You can run a workflow by hand on every plan, Free included. Schedules and webhook triggers come with the paid plans, from $29 a month.

## Once built, one call from your code

Once you have built a [method](/product/methods), it is one POST to /v1/runs from your backend, or a tool an AI agent calls over MCP. This is what “List onboarded solutions and devices” would look like.

Example request:

```
curl https://api.fous.com/v1/runs \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "fatoora.zatca.gov.sa/list_solutions_and_devices",
    "input": {
      "status": "Active",
      "certificate_expiry_before": "2027-01-31"
    }
  }'
```

Example response:

```
{
  "status": "completed",
  "data": {
    "devices": [
      {
        "common_name": "Acme-POS-Riyadh-01",
        "serial_number": "1-Acme|2-POS|3-7f3c21d0",
        "vat_number": "300000000000003",
        "organization_unit_name": "Riyadh Branch",
        "organization_name": "Acme Trading",
        "country": "SA",
        "status": "Active",
        "onboarding_date": "2025-01-14",
        "certificate_expiry_date": "2027-01-13",
        "revocation_date": null
      }
    ],
    "count": 1
  }
}
```

An example with invented data, not a ready-made endpoint. The method exists in your organization once you build it, and its name, inputs and fields follow your request.

## The ZATCA portal’s own options

The APIs ZATCA publishes are for e-invoicing: onboarding an e-invoice generation solution (EGS) and sending invoices, credit and debit notes for clearance or reporting. They do not cover returns, payments, certificates or the lists in the Fatoora portal. Those are used by hand, on the website or in the Zatca app.

| Option | What it covers | What it takes |
| --- | --- | --- |
| Fatoora onboarding APIs | Request a compliance CSID, run compliance checks for clearance and reporting, and request or renew a production CSID. | An OTP generated in the Fatoora portal for each EGS unit, valid for 1 hour. |
| Fatoora clearance and reporting APIs | Send one invoice, credit note or debit note at a time for clearance or for reporting. | An onboarded EGS unit with a production CSID. A separate simulation environment exists for testing. |
| Developer Portal | API documentation for building e-invoicing solutions. | Its own sign-up with an email address. Its credentials are separate from your Fatoora portal credentials. |
| The ZATCA portal by hand | Returns and certificates for Zakat, VAT, corporate income tax, excise, withholding and other taxes, and the Fatoora portal's lists. | A username and password with an SMS verification code; the Fatoora portal takes ERAD credentials (TIN or registered email, and password). |

Read on November 12, 2026: [Fatoora Portal User Manual](https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/Fatoora_Portal_User_Manual_English.pdf), [E-Services Interactive Guideline](https://zatca.gov.sa/en/HelpCenter/guidelines/Documents/E-Services_Interactive_Guideline.pdf), [Submit VAT Return](https://zatca.gov.sa/en/eServices/Pages/eServices_009.aspx).

## Signing in to the ZATCA portal

Companies and establishments sign in to the ZATCA portal with a username and password, then a verification code sent by SMS to the mobile. The Fatoora portal takes your ERAD credentials: TIN or registered email, and password. With Fous you sign in through ZATCA's own sign-in with your own account. The login is sealed with AES-256 and never shown to code or AI agents.

## Worth knowing

- **Two environments, onboarded separately**: The Fatoora portal and the Fatoora simulation portal are independent. A device onboarded in one does not appear in the other, so a method reads one environment.
- **OTPs last 1 hour**: Onboarding or renewing a CSID needs an OTP per EGS unit, generated in the Fatoora portal. Up to 100 can be generated in one request, and each is valid for 1 hour.
- **Revoking a CSID cannot be undone**: Once you confirm a revocation, the device is no longer active and has to be onboarded again as a new device. Keep revocation out of any unattended workflow.
- **A certificate needs a clean record**: A Zakat or tax certificate is issued only when there are no late returns or payments and no liabilities. The Immediate Certificate follows the Zakat return once the amount due is paid.

## More in Government: Middle East and Africa

- [CAC Company Registration Portal](https://fous.com/automate/cac-company-registration-portal.md)
- [CIPC eServices](https://fous.com/automate/cipc-eservices.md)
- [GDRFA Dubai Smart Services](https://fous.com/automate/gdrfa-dubai-smart-services.md)
- [eTIMS](https://fous.com/automate/etims.md)
- [Rev360](https://fous.com/automate/rev360.md)
- [Qiwa](https://fous.com/automate/qiwa.md)
- [ICP Smart Services](https://fous.com/automate/icp-smart-services.md)
- [KRA iTax](https://fous.com/automate/kra-itax.md)
- [SARS eFiling](https://fous.com/automate/sars-efiling.md)
- [SIMPL](https://fous.com/automate/simpl.md)
- [Egyptian Tax Authority e-Services](https://fous.com/automate/egyptian-tax-authority-e-services.md)
- [uFiling](https://fous.com/automate/ufiling.md)
- [EmaraTax](https://fous.com/automate/emaratax.md)
- [Mudad](https://fous.com/automate/mudad.md)

Other industries: [Prozorro](/automate/prozorro), [Guichet unique des formalités d'entreprises](/automate/guichet-unique-des-formalites-d-entreprises), [Odyssey File & Serve](/automate/odyssey-file-and-serve), [Barclays Mortgage Hub](/automate/barclays-mortgage-hub), [EFTPS](/automate/eftps), [SFS Vendor Portal](/automate/sfs-vendor-portal).

## Frequently asked questions

### Does ZATCA e-Services have an API?

Only for e-invoicing. ZATCA publishes Fatoora APIs to onboard an e-invoice generation solution and to send invoices, credit and debit notes for clearance or reporting. Returns, payments, certificates and the Fatoora portal's lists have no published API and are used in the portal.

### How do I see when my Fatoora CSIDs expire?

Open View List Of Solutions And Devices in the Fatoora portal. Each row shows the status, onboarding date, certificate expiry date and revocation date, and you can filter by expiry date or download the list.

### Where can I see why e-invoices were rejected?

In E-invoicing Statistics on the Fatoora portal. It counts accepted, accepted with warnings and rejected documents for the past 12 months, for reporting and clearance, and you can request detailed CSV files of the errors and warnings.

### What does a VAT return on the ZATCA portal ask for?

Taxpayer Details first, then sales VAT, purchase VAT and the total VAT amount, with attachments and notes. After you submit, a window confirms it and you can download the request form, and ZATCA sends an SMS and email.

### Is Fous affiliated with the Zakat, Tax and Customs Authority?

No. Fous is an independent product. You use it with your own ZATCA account, and a method reads and does only what that account can.

Fous is an independent product: it is not affiliated with, endorsed by or sponsored by the operator of ZATCA e-Services (Zakat, Tax and Customs Authority). The name is used only to say which system this page is about. Something here wrong or out of date? Write to legal@fous.com.