API Documentation

Complete reference for the ZATCA Integration API. Build compliant e-invoicing solutions with ease.

Base URL: https://zatcaapi.avtax.net

Authentication (Partner)

Manage your partner account and authentication.

Endpoint for Partner Account Authentication

POST /api/Partner/Login

This endpoint authenticates a partner and returns a Partner Access Token. This token is required for all EGS Unit management operations (Create, List, Revoke).

Request Body (JSON) 
{
  "email": "partner@example.com",
  "password": "SecurePassword123!"
}
Response 200 OK

Creates a new user and returns a JWT upon successful creation.

POST /api/Partner/CreateAccount
Request Body (JSON) 
{
  "email": "newpartner@example.com",
  "password": "SecurePassword123!",
  "confirmPassword": "SecurePassword123!",
  "fullName": "Partner Name",
  "phoneNumber": "+966500000000"
}
Response 200 OK

Endpoint for Changing Partner Account Password

POST /api/Partner/ChangePassword

This `ChangePassword` endpoint is designed to provide a secure method for partners to change their account password.

Request Body (JSON) 
{
  "currentPassword": "OldPassword123!",
  "newPassword": "NewPassword456!",
  "confirmNewPassword": "NewPassword456!"
}
Response 200 OK

Endpoint for Resetting User Password

POST /api/Partner/ResetPassword

This `ResetPassword` endpoint allows partners to reset their password by providing their email address.

Request Body (JSON) 
{
  "email": "partner@example.com"
}
Response 200 OK

Endpoint for Finalizing Password Reset

POST /api/Partner/FinalizePasswordReset

This `FinalizePasswordReset` endpoint allows users to finalize their password reset by providing their email, reset token, and new password.

Request Body (JSON) 
{
  "email": "partner@example.com",
  "token": "reset-token-string",
  "newPassword": "NewPassword789!",
  "confirmNewPassword": "NewPassword789!"
}
Response 200 OK

EGS Units

Manage E-Invoicing Generation Solution (EGS) Units.

Endpoint for EGS Unit Authentication

POST /api/UserAuthentication/LoginAsEgsUnit

Authenticates a specific EGS Unit using its `ClientId` and `ClientSecret`. Returns an EGS Unit Access Token required for all invoice operations.

Request Body (JSON) 
{
  "clientId": "fa005886-b6b4-4c0d-bd8a-a7dc4fe000b2",
  "clientSecret": "1cecadc0-4f32-49c7-bd51-ca1a5864d6b3"
}
Response 200 (OK) 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2025-11-21T12:33:58.3063591Z"
}
Response 401 (Unauthorized) 
{
  "errors": [
    "The client ID or client secret you entered is incorrect. Please check and try again."
  ]
}

Creates a new Egs Unit. Requires Partner Access Token

POST /api/EgsUnits/CreateNewEgsUnit

This endpoint allows for the creation of a new Egs Unit. It requires detailed organization information, tax registration data (VAT, Group VAT), a comprehensive address, and an OTP for verification.

Request Body (JSON) 
{
  "commonName": "Default Common Name",
  "organizationName": "Default Organization Name",
  "organizationUnitName": "Default Organization Unit Name",
  "serialNumber": "1-Manufacturer or Solution Provider Name|2-Model or Version|3-SerialNumber",
  "vatNumber": "300075588700003",
  "additionalID": "string",
  "additionalIDSchemeID": "None",
  "invoiceType": "1100",
  "industry": "Default Industry",
  "isProduction": false,
  "address": {
    "streetName": "شارع الأمير محمد بن عبد العزيز",
    "additionalStreetName": "الرياض",
    "buildingNumber": "1234",
    "plotIdentification": "5678",
    "citySubdivisionName": "الرياض",
    "cityName": "الرياض",
    "postalZone": "11564",
    "countrySubentity": "منطقة الرياض",
    "country": "SA"
  },
  "otp": "537888"
}
Response 200 (OK) 
{
  "clientId": "e403acba-5ce4-4628-9653-51279c5b907d",
  "clientSecret": "35e62a20-15ad-4070-a890-98e9f3728b1c",
  "egsUnitId": "913a1541-9d6d-44c2-bd2d-b26d4ecbbd94"
}
Response 400 (Bad Request) 
{
  "errors": [
    "The Egs Unit Name field is required.",
    "The Party Vat Id field is required."
  ]
}

Retrieves all Egs Units associated with the current partner. Requires Partner Access Token

GET /api/EgsUnits/GetEgsUnits
Response 200 (OK) 
[
  {
    "clientId": "69daa8bb-e8c0-45b0-a8fc-5d7da22f7d30",
    "clientSecret": "abb65afc-56a4-442f-83bb-cded60fe2b11",
    "egsUnitId": "245e46d1-82fd-477a-b5c6-69e581adc2fe",
    "organizationName": "Company Name 1",
    "vatNumber": "3000000000003",
    "additionalIDSchemeID": "None",
    "schemeIDName": "Commercial Registration Number",
    "additionalID": "1221356",
    "isProduction": true,
    "maximumNumberOfInvoicesPerMonth": 10000,
    "rateLimitPerMinute": 50
  }
]

Revokes the secret associated with a specific Egs Unit. Requires Partner Access Token

POST /api/EgsUnits/{egsUnitId}/revoke
Response 200 (OK) 
{
  "clientSecret": "new-client-secret-12345",
  "egsUnitId": "egsunit-id-67890"
}

Invoices

Submit and manage invoices.

Submits an invoice for clearance or reporting. Requires EGS Unit Access Token

POST /api/Invoice/SubmitInvoice

This endpoint allows you to submit an invoice. The system will validate, sign, and report/clear the invoice with ZATCA.

Request Body (JSON) 
{
  "documentType": "TaxInvoice",
  "invoiceIndicator": "Nominal",
  "currency": "SAR",
  "exchangeRate": null,
  "documentIssueDateTime": "2025-11-20T17:28:30.7241792",
  "supplyDate": "2025-11-20T17:28:30.7241803",
  "buyer": {
    "buyerAddress": {
      "streetName": null,
      "additionalStreetName": null,
      "buildingNumber": null,
      "plotIdentification": null,
      "citySubdivisionName": null,
      "cityName": "الرياض",
      "postalZone": null,
      "countrySubentity": null,
      "country": null
    },
    "buyerName": "Taj Al Mulook General Trading LLC",
    "buyerVatId": "310285784400003",
    "additionalIDSchemeID": "None",
    "additionalCustomerID": null
  },
  "documentLineItems": [
    {
      "lineItemName": "POLYETHYLENE HDPE HHM TR - 131",
      "lineItemPrice": 3950,
      "lineItemQty": 27.5,
      "discountOnLineItem": 0,
      "allowanceCode": null,
      "taxCategoryCode": "Z",
      "taxReasonCode": "VATEX_SA_32",
      "taxReasonDescription": null,
      "vatRateOnLineItem": 0
    },
    {
      "lineItemName": "POLYETHYLENE HDPE HHM TR - 132",
      "lineItemPrice": 3950,
      "lineItemQty": 27.5,
      "discountOnLineItem": 0,
      "allowanceCode": null,
      "taxCategoryCode": "S",
      "taxReasonCode": "None",
      "taxReasonDescription": null,
      "vatRateOnLineItem": 15
    }
  ],
  "referenceId": null,
  "documentId": "7788",
  "notes": null,
  "documentAllowanceOrChange": [
    {
      "allowanceChargeReasonCode": "95",
      "amount": 10,
      "taxCategoryCode": "S",
      "taxReasonCode": "None",
      "vatRate": 15
    }
  ],
  "invoiceTypeReason": null,
  "payment": {
    "paymentMethod": "InCash",
    "paymentAccountIdentifier": null,
    "paymentNote": null
  },
  "prepaymentDetails": [
    {
      "sequentialInvoiceUUID": "892a7039-d5bd-47e9-8f70-7fe44ad15ce9"
    }
  ]
}
Response 200 (OK) 
{
  "uuid": "03bfd07c-14f9-4f16-81ec-e526d86d5558",
  "status": "CLEARED",
  "validationResults": {
    "infoMessages": [
      {
        "type": "INFO",
        "code": "XSD_ZATCA_VALID",
        "message": "Complied with UBL 2.1 standards"
      }
    ],
    "status": "PASS"
  },
  "qrCodeString": "SampleQRCodeString...",
  "signedInvoice": "PD94bWwgdmVyc2lvbj0iMS4w..."
}
Response 400 (Bad Request) 
{
  "errors": [
    "The seller's tax registration number is required.",
    "The street must contain at least one character."
  ]
}
Response 403 (Forbidden) 
{
  "message": "You must be associated with a Egs Unit to access this resource.",
  "loginAsEgsUnitsUrl": "https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"
}

Retrieves the invoices associated with the current user. Requires EGS Unit Access Token

GET /api/Invoice/GetInvoices
Response 200 (OK) 
{
  "items": [
    {
      "invoiceStatus": {
        "invoiceUUID": "12345678-90ab-cdef-1234-567890abcdef",
        "invoiceStatus": "REPORTED"
      },
      "documentType": "SimplifiedTaxInvoice",
      "documentIssueDateTime": "2025-11-20T13:33:58.3035992+01:00",
      "buyer": {
        "buyerName": "Buyer Company Ltd."
      }
    }
  ],
  "pageNumber": 1,
  "totalPages": 10,
  "totalCount": 100
}

Retrieves the status of an invoice based on the provided Invoice UUID. Requires EGS Unit Access Token

GET /api/Invoice/GetInvoiceStatus/{invoiceUuid}/status
Response 200 (OK) 
{
  "invoiceUUID": "12345678-90ab-cdef-1234-567890abcdef",
  "invoiceStatus": "CLEARED",
  "invoiceClearanceResponse": {
    "clearanceStatus": "CLEARED"
  }
}
POST /api/Invoice/PrintInvoice/PrintA3

Generates a ZATCA-compliant PDF/A-3 file. You can specify a standard template or provide your own custom XSLT template.

Request Body (JSON) 
{
  "signedInvoice": "string",
  "logoUrl": "string",
  "pdfInvoiceBase64": "string",
  "pdfA3Templete": "ZatcaTemplate"
}
Response 200 (OK) 
%PDF-1.7 ... (Binary PDF Content)

Zatca UI Data

Helper endpoints to retrieve reference data for building your UI.

This endpoint retrieves all reasons for allowances.

GET /api/ZatcaUIData/ReasonForAllowances
Response 200 OK

This endpoint gets a list of all countries

GET /api/ZatcaUIData/Countries
Response 200 OK

This endpoint retrieves information on all available currencies.

GET /api/ZatcaUIData/Currencies
Response 200 OK

This endpoint fetches a list of different types of invoices

GET /api/ZatcaUIData/InvoiceTypes
Response 200 OK

Process a request To get all Tax Reason Codes

GET /api/ZatcaUIData/TaxReasonCodes
Response 200 OK

Process a request To get all Invoice Indicators

GET /api/ZatcaUIData/InvoiceIndicators
Response 200 OK

Process a request To get all Tax Categories

GET /api/ZatcaUIData/TaxCategories
Response 200 OK