العربية
Sign inSign up
العربية

Simple Fatoora API

V1

API reference for invoicing, customers, reports, and ZATCA Phase 2.

Base URLhttps://api.simplefatoora.com/v1
Simple Fatoora Developers

Simple Fatoora API V1

Use Simple Fatoora API V1 to connect invoicing, customer records, reports, and ZATCA Phase 2 workflows to your application.

Base URLhttps://api.simplefatoora.com/v1
Content typeJSON over HTTPS
Account & Access
POST/users/registration_intent

Create registration intent

Starts the email-verified account registration flow and returns a registration intent.

Public operationapplication/json

Request body

FieldTypeRequirement
registration_data
objectRequired
registration_data.first_name
stringOptional
registration_data.last_name
stringOptional
registration_data.email_id
string · emailRequired within the object
registration_data.password
string · passwordRequired within the object
registration_data.confirm_password
string · passwordRequired within the object
registration_data.company_name
stringRequired within the object
registration_data.mobile_number
stringOptional
registration_data.country_code
stringOptional
registration_data.company_registration_number
stringOptional
registration_data.company_vat_number
stringOptional
registration_data.address
stringOptional
registration_data.terms_and_conditions

Values: 1

integerRequired within the object
registration_data.source
stringOptional
registration_journey_id

A unique id generated by the integrating system for this registration attempt.

stringRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "registration_intent": "registration-intent-token",
    "expires_in": 86400
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Account & Access
POST/users/email_send_otp

Send email OTP

Sends a one-time verification code to the supplied email address.

Public operationapplication/json

Request body

FieldTypeRequirement
email_id
string · emailRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "OTP sent successfully",
    "is_register": false
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Account & Access
POST/users/email_verify_otp

Verify email OTP

Verifies the code sent to the email address. The verification is valid for the registration or password-reset flow.

Public operationapplication/json

Request body

FieldTypeRequirement
email_id
string · emailRequired
otp
integerRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "OTP verify successfully",
    "is_register": false
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Account & Access
POST/users/register_from_intent

Complete registration

Creates the account after email verification and returns the account's live and sandbox API keys.

Public operationapplication/json

Request body

FieldTypeRequirement
registration_intent
stringRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "Welcome to Simple Fatoora",
    "activation_method": "email_otp",
    "email_id": "developer@example.com",
    "first_name": "Developer",
    "last_name": "Account",
    "uuid": "session-uuid",
    "api_key": "live_api_key_example",
    "production_api_key": "live_api_key_example",
    "sandbox_api_key": "sandbox_api_key_example"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Account & Access
POST/users/validate_user

Get API keys from credentials

Validates account credentials and returns the live and sandbox API keys.

Public operationapplication/json

Request body

FieldTypeRequirement
user_name

Account email address

stringRequired
user_pass
string · passwordRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "api_key": "live_api_key_example",
  "production_api_key": "live_api_key_example",
  "sandbox_api_key": "sandbox_api_key_example",
  "response": "Validated successfully"
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Account & Access
POST/users/validate_user_api_key

Validate API key

Validates one account API key and returns the account's live and sandbox API keys.

Public operationapplication/json

Request body

FieldTypeRequirement
api_key
stringRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "api_key": "live_api_key_example",
  "production_api_key": "live_api_key_example",
  "sandbox_api_key": "sandbox_api_key_example",
  "active_environment": "live",
  "response": "Validated successfully"
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Account & Access
POST/users/update_password

Reset password

Sets a new password using the password-reset UUID returned after email verification.

Public operationapplication/json

Request body

FieldTypeRequirement
uuid
stringRequired
password
string · passwordRequired
confirm_password
string · passwordRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "Password updated successfully",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Business Profile
GET/users/get_profile

Get business profile

Returns business details and invoice display settings for the authenticated account.

API key required

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "user_id": 123,
    "company_name": "Example Company",
    "email_id": "developer@example.com",
    "address": "Riyadh",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "tax_setup_status": "vat_registered",
    "tax_registration_status": "vat_registered",
    "is_vat_registered": true,
    "environment": "live",
    "is_sandbox": false,
    "production_api_key": "live_api_key_example",
    "sandbox_api_key": "sandbox_api_key_example",
    "send_mail": 1,
    "client_send_mail": 1
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Business Profile
POST/users/update_profile

Update business profile

Updates business details and supported invoice display settings.

API key requiredapplication/json

Request body

FieldTypeRequirement
first_name
stringOptional
last_name
stringOptional
company_name
stringOptional
address
stringOptional
country_code
stringOptional
mobile_number
stringOptional
tax_setup_status

Values: vat_registered, non_vat

stringOptional
company_registration_number
stringOptional
company_vat_number
stringOptional
notes
stringOptional
footer_text
stringOptional
send_mail

Values: 0, 1

integerOptional
client_send_mail

Values: 0, 1

integerOptional
zero_vat_default

Saved account default. Send null to clear. Read it and explicitly copy the applicable classification to invoice lines; API creation does not apply or change it automatically.

objectOptional
zero_vat_default.category

Z = zero-rated; E = exempt; O = outside scope. Omit to derive from reason_code. Values: Z, E, O

stringOptional
zero_vat_default.reason_code

Select the code that applies to the supply. Values: VATEX-SA-32, VATEX-SA-33, VATEX-SA-34-1, VATEX-SA-34-2, VATEX-SA-34-3, VATEX-SA-34-4, VATEX-SA-34-5, VATEX-SA-35, VATEX-SA-36, VATEX-SA-EDU, VATEX-SA-HEA, VATEX-SA-MLTRY, VATEX-SA-29, VATEX-SA-29-7, VATEX-SA-30, VATEX-SA-OOS

stringRequired within the object
zero_vat_default.reason

Required specific explanation for VATEX-SA-OOS. Other codes supply a standard description when omitted. Max length: 500

stringOptional
invoice_logo

Legacy profile preference, retained for compatibility. It does not override the uploaded company logo. Use upload_profile_image to change that logo. Values: 0, 1

integerOptional
show_simplified_customer_info

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
show_pdf_item_id

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
show_pdf_issuer_address

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
show_pdf_issuer_mobile

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
show_pdf_issuer_email

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
show_pdf_customer_address

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
show_pdf_customer_mobile

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
show_pdf_customer_email

1 shows this information in generated PDFs; 0 hides it, subject to required invoice information. Values: 0, 1

integerOptional
district

Business address component. Phase 2 identity restrictions apply.

stringOptional
building_number

Business address component. Phase 2 identity restrictions apply.

stringOptional
city

Business address component. Phase 2 identity restrictions apply.

stringOptional
postal_code

Business address component. Phase 2 identity restrictions apply.

stringOptional
street_name

Business address component. Phase 2 identity restrictions apply.

stringOptional
business_identification_type

Seller identification type. Use CRN for commercial registration; otherwise provide the applicable official identification. Omit both fields to preserve an existing identity. Values: CRN, MOM, MLS, 700, SAG, OTH

stringOptional
business_identification_number

Number matching business_identification_type. Commercial registration is 10 digits; a unified business number is 10 digits starting with 7. Other types use letters and digits. Max length: 150

stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "Profile updated successfully",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Clients
GET/client/kyc_category_list

List client categories

Returns available client KYC categories.

API key required

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "categories": [
      {
        "id": 1,
        "title": "Retail",
        "ar_title": "التجزئة",
        "position": 1,
        "status": 1
      }
    ]
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Clients
POST/client/create

Create client

Creates a client record for future invoices and documents.

API key requiredapplication/json

Request body

FieldTypeRequirement
first_name
stringRequired
email_id
string · emailOptional
mobile_number
stringRequired
country_code
stringRequired
address
stringOptional
company_registration_number
stringOptional
company_vat_number
stringOptional
category_id

One or more numeric category ids separated by commas.

stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "User created successfully",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Clients
POST/client/update

Update client

Updates an existing client record. Include the client id with the fields to change.

API key requiredapplication/json

Request body

FieldTypeRequirement
id
integerRequired
first_name
stringOptional
email_id
string · emailOptional
mobile_number
stringOptional
country_code
stringOptional
address
stringOptional
company_registration_number
stringOptional
company_vat_number
stringOptional
category_id
stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "User updated successfully",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Clients
GET/client/get_byid/{client_id}

Get client

Returns one client owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement
client_id
pathintegerRequired

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "id": 123,
    "user_id": 123,
    "first_name": "Example Customer",
    "email_id": "customer@example.com",
    "mobile_number": "500000000",
    "country_code": "+966",
    "address": "Riyadh",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "status": 1
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Clients
POST/client/get_all

List clients

Returns clients owned by the authenticated account with optional pagination and search.

API key requiredapplication/json

Request body

FieldTypeRequirement
page
integerOptional
per_page
integerOptional
limit
integerOptional
search_key
stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "users": [
      {
        "id": 123,
        "full_name": "Example Customer",
        "email_id": "customer@example.com",
        "mobile_number": "500000000",
        "country_code": "+966",
        "address": "Riyadh",
        "client_type": 2
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Clients
DELETE/client/delete/{client_id}

Delete client

Deletes one client owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement
client_id
pathintegerRequired

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "User deleted successfully"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Products
GET/invoice/products/search

Search products

Searches previously used products by name or description.

API key required

Parameters

FieldLocationTypeRequirement
search_key

Product search text

querystringOptional
limit
queryintegerOptional

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "products": [
      {
        "id": 123,
        "product_id": "P0001",
        "description": "Example item",
        "unit_price": 100,
        "vat_percent": 15,
        "last_used_on": "2026-08-30T20:41:45"
      }
    ]
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Products
POST/invoice/products/list

List products

Returns products previously used by the authenticated account.

API key requiredapplication/json

Request body

FieldTypeRequirement
page
integerOptional
per_page
integerOptional
limit
integerOptional
search_key
stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "products": [
      {
        "id": 123,
        "product_id": "P0001",
        "description": "Example item",
        "unit_price": 100,
        "vat_percent": 15,
        "last_used_on": "2026-08-30T20:41:45"
      }
    ]
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoices & Documents
POST/invoice/create

Create invoice or document

Creates a simplified invoice, standard invoice, purchase invoice, credit note, or debit note. Credit and debit notes require the parent document's invoice_number as parent_invoice_number. ZATCA processing follows the account and API-key environment. To convert an existing quotation, also send its id as draft_id, set created_type to quotation, and use quotation:{id} as source_uid. Repeating that same quotation conversion returns the original document instead of creating a duplicate. Set zero_vat_version=1 for classified zero-rate sales. Lines in the same VAT category must use the same classification and reason. Export codes VATEX-SA-32/33 require invoice_type=1, a foreign buyer_country, client_name, street_name and city. A stable internal buyer reference is generated if needed; no government identity is generated. Ordinary purchases are internal documents. Document emails follow the current account permissions; sandbox customer mail is disabled.

API key requiredapplication/json

Parameters

FieldLocationTypeRequirement
Idempotency-Key

Optional for created_type=api (the default). Reuse only with identical data and the same account/environment. Completed requests replay the original document; different data, processing or uncertain outcomes return 409. A failure before any invoice is saved releases the key.

headerstringOptional

Request body

FieldTypeRequirement
invoice_type

0 simplified invoice, 1 standard invoice, 2 purchase invoice, 3 credit note, 4 debit note. Values: 0, 1, 2, 3, 4

integerRequired
client_type

Values: 0, 1, 2

integerOptional
taxes_included

Values: 0, 1

integerOptional
client_id
integerOptional
client_name
stringOptional
client_address
stringOptional
client_email_id
string · emailOptional
client_vat_number
stringOptional
date_time

Accepted for compatibility and validated when supplied. Issue date/time is always assigned by the server in Asia/Riyadh. Use transaction_date for a separate supply/purchase date.

stringOptional
reference_number
stringOptional
parent_invoice_number

Required for credit and debit notes. Use the invoice_number returned for the original document in the same API-key environment.

stringOptional
document_reason

Reason for a credit or debit note.

stringOptional
created_type

Optional source channel identifier.

stringOptional
source_uid

Optional source record identifier for supported connector channels.

stringOptional
draft_id

Optional quotation id to mark as converted after this document is created. Use with created_type=quotation and source_uid=quotation:{id}.

integerOptional
invoice_detail
array<object>Required
invoice_detail[].description
stringRequired within the object
invoice_detail[].unit_price
numberRequired within the object
invoice_detail[].quantity

Positive quantity. Fractional quantities are supported with up to 6 decimal places. Precision: 0.000001

numberRequired within the object
invoice_detail[].vat_percent_product
numberOptional
invoice_detail[].vat_percent

VAT percentage. Takes precedence over vat_percent_product when supplied.

numberOptional
invoice_detail[].discount_percent
numberOptional
invoice_detail[].zero_vat

Classification of a zero-rate sales line. The business selects the applicable treatment. Codes follow the ZATCA XML Implementation Standard 1.2, section 11.2.4.

objectOptional
invoice_detail[].zero_vat.category

Z = zero-rated; E = exempt; O = outside scope. Omit to derive from reason_code. Values: Z, E, O

stringOptional
invoice_detail[].zero_vat.reason_code

Select the code that applies to the supply. Values: VATEX-SA-32, VATEX-SA-33, VATEX-SA-34-1, VATEX-SA-34-2, VATEX-SA-34-3, VATEX-SA-34-4, VATEX-SA-34-5, VATEX-SA-35, VATEX-SA-36, VATEX-SA-EDU, VATEX-SA-HEA, VATEX-SA-MLTRY, VATEX-SA-29, VATEX-SA-29-7, VATEX-SA-30, VATEX-SA-OOS

stringRequired within the object
invoice_detail[].zero_vat.reason

Required specific explanation for VATEX-SA-OOS. Other codes supply a standard description when omitted. Max length: 500

stringOptional
invoice_detail[].product_id

Optional item identifier printed when the profile enables Item ID.

stringOptional
invoice_detail[].discount_type

1 = percentage; 2 = fixed amount per unit. Use with discount_value. Values: 1, 2

integerOptional
invoice_detail[].discount_value

Discount percentage or per-unit amount according to discount_type.

numberOptional
invoice_detail[].total_discount

Alternative fixed discount for the entire line. Supply one discount representation per line.

numberOptional
zero_vat_version

Set to 1 to require a valid classification on every zero-rate tax sales line. Existing clients that omit it retain compatibility validation. Values: 1

integerOptional
transaction_date_mode

current uses the server date in Asia/Riyadh; previous requires transaction_date before today. Sales and purchases only. Values: current, previous

stringOptional
transaction_date

Supply date for sales or purchase date for purchases. YYYY-MM-DD. Reports use this date; notes use their own issue date.

string · dateOptional
buyer_country

ISO 3166-1 alpha-2 country. Required foreign country for exports.

stringOptional
currency

ISO 4217 currency. Defaults to SAR. Stored document totals are in SAR; original_currency and converted_value describe the original currency and conversion.

stringOptional
shipping_charge

Shipping amount in the request currency.

numberOptional
shipping_taxable

Whether shipping is taxable at the document shipping rate. Values: 0, 1

integerOptional
extra_discount

Document-level discount. Use item discounts for mixed zero categories or outside-scope items.

numberOptional
notes

Notes for this document. Blank or omitted uses the profile default; does not update that default.

stringOptional
footer_text

Terms for this document. Blank or omitted uses the profile default.

stringOptional
street_name

Counterparty street; required for exports.

stringOptional
city

Counterparty city; required for exports.

stringOptional
district

Counterparty district.

stringOptional
building_number

Counterparty building number.

stringOptional
postal_code

Counterparty postal code.

stringOptional
client_cr_number

Counterparty commercial registration.

stringOptional
client_contact_number

Counterparty phone number without calling code.

stringOptional
client_country_code

Phone calling code; distinct from buyer_country.

stringOptional

Zero-VAT classification codes

For each zero-rate sales line, send the applicable code in zero_vat.reason_code. Set zero_vat_version to 1 to validate the classification on every zero-rate sales line.

ZATCA electronic invoice specifications
VATEX-SA-32Zero-rated (Z)
Export of goods
VATEX-SA-33Zero-rated (Z)
Export of services
VATEX-SA-34-1Zero-rated (Z)
International transport of goods
VATEX-SA-34-2Zero-rated (Z)
International transport of passengers
VATEX-SA-34-3Zero-rated (Z)
Services incidental to international passenger transport
VATEX-SA-34-4Zero-rated (Z)
Supply of qualifying means of transport
VATEX-SA-34-5Zero-rated (Z)
Services relating to goods or passenger transport (Article 25)
VATEX-SA-35Zero-rated (Z)
Medicines and medical equipment
VATEX-SA-36Zero-rated (Z)
Qualifying metals
VATEX-SA-EDUZero-rated (Z)
Private education for Saudi citizens
VATEX-SA-HEAZero-rated (Z)
Private healthcare for Saudi citizens
VATEX-SA-MLTRYZero-rated (Z)
Supply of qualifying military goods
VATEX-SA-29Exempt (E)
Exempt financial services (Article 29)
VATEX-SA-29-7Exempt (E)
Life insurance services (Article 29)
VATEX-SA-30Exempt (E)
Exempt real estate transactions (Article 30)
VATEX-SA-OOSOutside scope (O)
Outside the scope of VAT

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "id": 123,
    "invoice_number": "ST123-456",
    "invoice_type_code": 0,
    "document_label": "Simplified Tax Invoice",
    "document_label_ar": "فاتورة ضريبية مبسطة",
    "seller_tax_status": "vat_registered",
    "is_tax_document": true,
    "vat": 22.5,
    "total": 172.5,
    "date_time": "2026-10-15 12:00:00",
    "transaction_date": null,
    "environment": "sandbox",
    "pdf_ready": false,
    "xml_available": false
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
409Idempotency conflict or request awaiting completion/review
application/json
{
  "status": false,
  "message": "This request is processing or requires review. Check its document before retrying.",
  "response": {
    "invoice_id": 123
  }
}
Invoices & Documents
POST/invoice/get_all

List invoices and documents

Returns documents for the API-key environment with pagination and filters.

API key requiredapplication/json

Request body

FieldTypeRequirement
page
integerOptional
per_page
integerOptional
limit
integerOptional
search_key
stringOptional
include_all_invoice_types

Values: 0, 1

integerOptional
invoice_types
array<integer>Optional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "invoices": [
      {
        "id": 123,
        "invoice_number": "ST123-456",
        "invoice_type": 0,
        "date_time": "2026-08-30 23:41:18",
        "reference_number": "POS-1001",
        "total": 115,
        "invoice": "https://example.com/invoices/ST123-456.pdf",
        "pdf_ready": true,
        "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
        "xml_available": true,
        "xml_archive_state": "reported",
        "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
        "environment": "live",
        "is_test": false
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoices & Documents
GET/invoice/get_byid/{document_id}

Get invoice or document

Returns one document owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement
document_id
pathintegerRequired

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "id": 123,
    "invoice_number": "ST123-456",
    "invoice_type": 0,
    "date_time": "2026-08-30 23:41:18",
    "reference_number": "POS-1001",
    "seller_name": "Example Company",
    "seller_vat_number": "300000000000003",
    "buyer_name": "Example Customer",
    "buyer_email_id": "customer@example.com",
    "sub_total": 100,
    "vat": 15,
    "total": 115,
    "invoice": "https://example.com/invoices/ST123-456.pdf",
    "qrcode": "https://example.com/invoices/ST123-456-qr.png",
    "pdf_ready": true,
    "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
    "xml_available": true,
    "xml_archive_state": "reported",
    "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
    "environment": "live",
    "invoice_details": [
      {
        "description": "Example item",
        "unit_price": 100,
        "quantity": 1,
        "vat_percent": 15,
        "vat": 15,
        "total": 115
      }
    ],
    "document_label": "Simplified Tax Invoice",
    "document_label_ar": "فاتورة ضريبية مبسطة",
    "seller_tax_status": "vat_registered",
    "is_tax_document": true,
    "transaction_date": "2026-09-15"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoices & Documents
GET/invoice/pdf/{document_id}

Download invoice PDF

Downloads the PDF for one issued document owned by the API-key account. Use download=1 for attachment disposition.

API key required

Parameters

FieldLocationTypeRequirement
document_id
pathintegerRequired
download
queryintegerOptional

Request body

This operation has no request body.

Responses

200PDF binary response
application/pdf
%PDF binary document
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoices & Documents
GET/invoice/xml/{document_id}

Download XML

Downloads the XML for an eligible Phase 2 tax document owned by the API-key account.

API key required

Parameters

FieldLocationTypeRequirement
document_id
pathintegerRequired

Request body

This operation has no request body.

Responses

200Final XML binary response
application/xml
<?xml version="1.0"?><Invoice>...</Invoice>
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoices & Documents
POST/invoice/archive/export

Export invoice archive

Downloads one ZIP part, up to 250 documents and 50 MB of document bytes; each file is limited to 10 MB. Follow X-SF-Archive-Next using cursor until empty. Each ZIP includes manifest.csv and archive-info.json with completion, next cursor and unavailable counts. Unavailable files are listed as skipped. A fresh export retries availability; continuation preserves the original document selection. Date filters select the issue date, not the supply/purchase date used by reports.

API key requiredapplication/json

Request body

FieldTypeRequirement
format

Values: pdf, xml

stringRequired
start_date

Optional. Supply together with end_date; omit both for all dates.

string · dateOptional
end_date

Optional. Supply together with start_date; omit both for all dates.

string · dateOptional
invoice_types

Optional. Omit to include every issued invoice/note type.

array<integer>Optional
cursor

Continuation token from X-SF-Archive-Next or archive-info.json. Keep format unchanged; filters are frozen in the token. Omit to start a new export.

stringOptional

Responses

200ZIP archive response
application/zip

X-SF-Archive-Next: Next cursor; empty on the final part.

X-SF-Archive-Part: Part number.

X-SF-Archive-Exported: Files included in this part.

X-SF-Archive-Skipped: Unavailable files skipped in this part.

Binary ZIP archive with documents and manifest.csv
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoices & Documents
GET/invoice/get_byinvoice_number

Find document by invoice number

Finds one owned document in the API-key environment. Success returns the document directly, without a response envelope. Its integer status is the stored document state. An unavailable document returns the usual error object with boolean status=false.

API key required

Parameters

FieldLocationTypeRequirement
invoice_number
querystringRequired

Request body

This operation has no request body.

Responses

200Successful response
application/json
{
  "id": 123,
  "invoice_number": "ST123-456",
  "status": 1,
  "invoice_type": 0,
  "environment": "live"
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Quotations
POST/drafts/create

Create quotation

Creates a quotation. The quotation document is supplied as a JSON-encoded string in json_data.

API key requiredapplication/json

Request body

FieldTypeRequirement
json_data

JSON-encoded QuotationPayload. Use vat_percent on quotation lines. No supply/purchase date applies until conversion.

stringRequired
json_data.document_kind

Values: quotation

stringRequired within the object
json_data.client_type

Values: 0, 1, 2

integerOptional
json_data.client_name
stringOptional
json_data.client_address
stringOptional
json_data.client_email_id
string · emailOptional
json_data.client_vat_number
stringOptional
json_data.buyer_country

ISO 3166-1 alpha-2 country. Required foreign country for exports.

stringOptional
json_data.street_name

Counterparty street; required for exports.

stringOptional
json_data.city

Counterparty city; required for exports.

stringOptional
json_data.district

Counterparty district.

stringOptional
json_data.building_number

Counterparty building number.

stringOptional
json_data.postal_code

Counterparty postal code.

stringOptional
json_data.notes

Notes for this document. Blank or omitted uses the profile default; does not update that default.

stringOptional
json_data.footer_text

Terms for this document. Blank or omitted uses the profile default.

stringOptional
json_data.invoice_detail
array<object>Required within the object
json_data.invoice_detail[].description
stringRequired within the object
json_data.invoice_detail[].unit_price
numberRequired within the object
json_data.invoice_detail[].quantity

Positive quantity. Fractional quantities are supported with up to 6 decimal places. Precision: 0.000001

numberRequired within the object
json_data.invoice_detail[].vat_percent

VAT percentage. Takes precedence over vat_percent_product when supplied.

numberOptional
json_data.invoice_detail[].discount_percent
numberOptional
json_data.invoice_detail[].zero_vat

Classification of a zero-rate sales line. The business selects the applicable treatment. Codes follow the ZATCA XML Implementation Standard 1.2, section 11.2.4.

objectOptional
json_data.invoice_detail[].zero_vat.category

Z = zero-rated; E = exempt; O = outside scope. Omit to derive from reason_code. Values: Z, E, O

stringOptional
json_data.invoice_detail[].zero_vat.reason_code

Select the code that applies to the supply. Values: VATEX-SA-32, VATEX-SA-33, VATEX-SA-34-1, VATEX-SA-34-2, VATEX-SA-34-3, VATEX-SA-34-4, VATEX-SA-34-5, VATEX-SA-35, VATEX-SA-36, VATEX-SA-EDU, VATEX-SA-HEA, VATEX-SA-MLTRY, VATEX-SA-29, VATEX-SA-29-7, VATEX-SA-30, VATEX-SA-OOS

stringRequired within the object
json_data.invoice_detail[].zero_vat.reason

Required specific explanation for VATEX-SA-OOS. Other codes supply a standard description when omitted. Max length: 500

stringOptional
json_data.invoice_detail[].product_id

Optional item identifier printed when the profile enables Item ID.

stringOptional
json_data.company_name

Business counterparty name.

stringOptional
json_data.buyer_name

Individual counterparty name.

stringOptional
environment

The API key remains authoritative for the environment. Values: live, sandbox

stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "Draft created successfully",
    "id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Quotations
POST/drafts/update

Update quotation

Updates an existing quotation and its JSON-encoded document data.

API key requiredapplication/json

Request body

FieldTypeRequirement
json_data

JSON-encoded QuotationPayload. Use vat_percent on quotation lines. No supply/purchase date applies until conversion.

stringRequired
json_data.document_kind

Values: quotation

stringRequired within the object
json_data.client_type

Values: 0, 1, 2

integerOptional
json_data.client_name
stringOptional
json_data.client_address
stringOptional
json_data.client_email_id
string · emailOptional
json_data.client_vat_number
stringOptional
json_data.buyer_country

ISO 3166-1 alpha-2 country. Required foreign country for exports.

stringOptional
json_data.street_name

Counterparty street; required for exports.

stringOptional
json_data.city

Counterparty city; required for exports.

stringOptional
json_data.district

Counterparty district.

stringOptional
json_data.building_number

Counterparty building number.

stringOptional
json_data.postal_code

Counterparty postal code.

stringOptional
json_data.notes

Notes for this document. Blank or omitted uses the profile default; does not update that default.

stringOptional
json_data.footer_text

Terms for this document. Blank or omitted uses the profile default.

stringOptional
json_data.invoice_detail
array<object>Required within the object
json_data.invoice_detail[].description
stringRequired within the object
json_data.invoice_detail[].unit_price
numberRequired within the object
json_data.invoice_detail[].quantity

Positive quantity. Fractional quantities are supported with up to 6 decimal places. Precision: 0.000001

numberRequired within the object
json_data.invoice_detail[].vat_percent

VAT percentage. Takes precedence over vat_percent_product when supplied.

numberOptional
json_data.invoice_detail[].discount_percent
numberOptional
json_data.invoice_detail[].zero_vat

Classification of a zero-rate sales line. The business selects the applicable treatment. Codes follow the ZATCA XML Implementation Standard 1.2, section 11.2.4.

objectOptional
json_data.invoice_detail[].zero_vat.category

Z = zero-rated; E = exempt; O = outside scope. Omit to derive from reason_code. Values: Z, E, O

stringOptional
json_data.invoice_detail[].zero_vat.reason_code

Select the code that applies to the supply. Values: VATEX-SA-32, VATEX-SA-33, VATEX-SA-34-1, VATEX-SA-34-2, VATEX-SA-34-3, VATEX-SA-34-4, VATEX-SA-34-5, VATEX-SA-35, VATEX-SA-36, VATEX-SA-EDU, VATEX-SA-HEA, VATEX-SA-MLTRY, VATEX-SA-29, VATEX-SA-29-7, VATEX-SA-30, VATEX-SA-OOS

stringRequired within the object
json_data.invoice_detail[].zero_vat.reason

Required specific explanation for VATEX-SA-OOS. Other codes supply a standard description when omitted. Max length: 500

stringOptional
json_data.invoice_detail[].product_id

Optional item identifier printed when the profile enables Item ID.

stringOptional
json_data.company_name

Business counterparty name.

stringOptional
json_data.buyer_name

Individual counterparty name.

stringOptional
environment

The API key remains authoritative for the environment. Values: live, sandbox

stringOptional
id
integerRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "Draft updated successfully"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Quotations
POST/drafts/get_all

List quotations

Returns quotations for the selected API-key environment.

API key requiredapplication/json

Request body

FieldTypeRequirement
page
integerOptional
per_page
integerOptional
limit
integerOptional
search_key
stringOptional
document_kind
stringOptional
environment

Values: live, sandbox

stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "drafts": [
      {
        "id": 123,
        "environment": "sandbox",
        "created_on": "2026-08-30 20:41:45",
        "json_data": "{\"document_kind\":\"quotation\",\"client_name\":\"Example Customer\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1}]}"
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Quotations
GET/drafts/get_byid/{quotation_id}

Get quotation

Returns one quotation owned by the authenticated account, with quotation_summary containing the same calculated items and totals as its PDF. Quotations remain distinct from issued invoices.

API key required

Parameters

FieldLocationTypeRequirement
quotation_id
pathintegerRequired

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "id": 123,
    "environment": "sandbox",
    "status": 1,
    "created_on": "2026-08-30 20:41:45",
    "json_data": "{\"document_kind\":\"quotation\",\"client_name\":\"Example Customer\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1}]}",
    "quotation_summary": {
      "quotation_reference": "Q-00123",
      "document_kind": "quotation",
      "invoice_issued": false,
      "currency": "SAR",
      "items": [
        {
          "description": "Example item",
          "quantity": 1,
          "unit_price": 100,
          "discount_percent": 0,
          "discount": 0,
          "vat_percent": 0,
          "vat": 0,
          "total": 100
        }
      ],
      "sub_total": 100,
      "discount": 0,
      "taxable_amount": 100,
      "vat": 0,
      "total": 100
    }
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Quotations
GET/drafts/quotation_pdf/{quotation_id}

Download quotation PDF

Returns the quotation PDF. Set download to 1 to request a file attachment.

API key required

Parameters

FieldLocationTypeRequirement
quotation_id
pathintegerRequired
download
queryintegerOptional

Request body

This operation has no request body.

Responses

200Quotation PDF
application/pdf
%PDF-1.7 (binary PDF content)
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Quotations
DELETE/drafts/delete/{quotation_id}

Delete quotation

Deletes one quotation owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement
quotation_id
pathintegerRequired

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "message": "Draft deleted successfully"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Reports
POST/invoice/get_report

Get sales report

Returns monthly sales, purchase or VAT report data for the requested period and type. Sales and purchases use the saved transaction date when available; credit and debit notes use their issue date. The revenue_dashboard type uses issue dates. All amounts are in SAR. The API key determines the account and environment.

API key requiredapplication/json

Request body

FieldTypeRequirement
start_date
string · dateRequired
end_date
string · dateRequired
type

Values: revenue_dashboard, sale_report, purchase_report, vat_report

stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "sale_report": [
      {
        "month_name": "September 2026",
        "company_name": "Example Company",
        "total": 460,
        "vat": 60,
        "net": 400,
        "sale_net": 400,
        "sale_vat": 60,
        "sale_total": 460,
        "credit_net": 0,
        "credit_vat": 0,
        "credit_total": 0
      }
    ]
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Reports
POST/invoice/get_vat_return_report

Get VAT return report

Returns VAT-return figures for a date range. Sales and purchases use their saved transaction date when present, otherwise issue date. Credit/debit notes use their own issue date. Amounts are SAR. The API key selects the environment; request user_id/environment cannot change scope.

API key requiredapplication/json

Request body

FieldTypeRequirement
start_date
string · dateRequired
end_date
string · dateRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "sale_sub_total": 1000,
    "sale_vat": 150,
    "sale_discount": 0,
    "purchase_sub_total": 200,
    "purchase_vat": 30,
    "purchase_discount": 0,
    "credit_total": 0,
    "debit_total": 0,
    "vat_out": 150,
    "vat_in": 30,
    "vat_payable": 120
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Reports
POST/invoice/export_documents_excel

Download sales or purchase Excel

Downloads the sales or purchase records for the authenticated account as an Excel workbook. The start and end dates are inclusive. Records follow the same transaction-date rules as the corresponding report. Set lang to en or ar.

API key requiredapplication/json

Request body

FieldTypeRequirement
start_date
string · dateRequired
end_date
string · dateRequired
type

Values: sale_report, purchase_report

stringRequired
lang

Values: en, ar

stringOptional

Responses

200Successful response
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Binary XLSX workbook
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Reports
POST/invoice/export_vat_excel

Download VAT Excel

Downloads the aggregate VAT-return report figures as an Excel workbook. The start and end dates are inclusive. Figures combine the applicable tax categories; the workbook does not provide a breakdown by exemption code. Set lang to en or ar.

API key requiredapplication/json

Request body

FieldTypeRequirement
start_date
string · dateRequired
end_date
string · dateRequired
lang

Values: en, ar

stringOptional

Responses

200Successful response
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Binary XLSX workbook
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
ZATCA Phase 2
GET/zatca-phase2/status

Get Phase 2 status

Returns the current ZATCA Phase 2 onboarding state for the API-key environment. Read next_step, error_category and error_code before recovery. A terminal or expired compliance session requires a fresh CSR and a new ZATCA OTP. Retrying is available only when can_retry_compliance_checks is true. Integrated legal identity fields are protected.

API key required

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "draft",
    "status_label": "Draft",
    "next_step": "review_info",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
ZATCA Phase 2
POST/zatca-phase2/save-draft

Save Phase 2 draft

Saves the establishment and device information used for Phase 2 onboarding.

API key requiredapplication/json

Request body

FieldTypeRequirement
source_channel
stringOptional
company_name
stringRequired
organization_name
stringRequired
organization_identifier
stringRequired
organization_unit_name
stringRequired
company_registration_number
stringOptional
company_vat_number
stringRequired
industry_business_category
stringRequired
street_name
stringRequired
building_number
stringRequired
district
stringRequired
city
stringRequired
postal_code
stringRequired
country_name
stringRequired
business_identification_type

Seller identification type. Use CRN for commercial registration; otherwise provide the applicable official identification. Omit both fields to preserve an existing identity. Values: CRN, MOM, MLS, 700, SAG, OTH

stringOptional
business_identification_number

Number matching business_identification_type. Commercial registration is 10 digits; a unified business number is 10 digits starting with 7. Other types use letters and digits. Max length: 150

stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "draft",
    "status_label": "Draft",
    "next_step": "review_info",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
ZATCA Phase 2
POST/zatca-phase2/generate-csr

Generate CSR

Generates the certificate signing request for the supplied Phase 2 business data. Read next_step, error_category and error_code before recovery. A terminal or expired compliance session requires a fresh CSR and a new ZATCA OTP. Retrying is available only when can_retry_compliance_checks is true. Integrated legal identity fields are protected.

API key requiredapplication/json

Request body

FieldTypeRequirement
source_channel
stringOptional
company_name
stringRequired
organization_name
stringRequired
organization_identifier
stringRequired
organization_unit_name
stringRequired
company_registration_number
stringOptional
company_vat_number
stringRequired
industry_business_category
stringRequired
street_name
stringRequired
building_number
stringRequired
district
stringRequired
city
stringRequired
postal_code
stringRequired
country_name
stringRequired
business_identification_type

Seller identification type. Use CRN for commercial registration; otherwise provide the applicable official identification. Omit both fields to preserve an existing identity. Values: CRN, MOM, MLS, 700, SAG, OTH

stringOptional
business_identification_number

Number matching business_identification_type. Commercial registration is 10 digits; a unified business number is 10 digits starting with 7. Other types use letters and digits. Max length: 150

stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123,
    "csr_generated_on": "2026-08-30T20:42:00Z",
    "csr_expires_on": "2026-08-31T20:42:00Z"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
ZATCA Phase 2
POST/zatca-phase2/submit-otp

Submit ZATCA OTP

Submits the OTP generated in the ZATCA portal to continue onboarding.

API key requiredapplication/json

Request body

FieldTypeRequirement
source_channel
stringOptional
otp
stringRequired

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "production_issued",
    "status_label": "Integrated",
    "next_step": "completed",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": true,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": true,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123,
    "activated_on": "2026-08-30T20:48:00Z",
    "production_issued_on": "2026-08-30T20:48:00Z"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
ZATCA Phase 2
POST/zatca-phase2/retry-compliance

Retry compliance checks

Retries the Phase 2 compliance-document checks after a recoverable onboarding result. Read next_step, error_category and error_code before recovery. A terminal or expired compliance session requires a fresh CSR and a new ZATCA OTP. Retrying is available only when can_retry_compliance_checks is true. Integrated legal identity fields are protected.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "production_issued",
    "status_label": "Integrated",
    "next_step": "completed",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": true,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": true,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
ZATCA Phase 2
POST/zatca-phase2/refresh-status

Refresh Phase 2 status

Refreshes the Phase 2 state from the current onboarding records.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
ZATCA Phase 2
POST/zatca-phase2/renew

Renew Phase 2 integration

Starts a controlled renewal of the account's Phase 2 integration.

API key requiredapplication/json

Request body

FieldTypeRequirement
source_channel
stringOptional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": true,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoice Email Sender
GET/users/invoice-email-sender

Read invoice email sender

Returns the account-wide invoice email sender settings, DNS verification records, current revision and recent delivery statuses. Both live and sandbox keys can read these settings; only live keys can change them.

API key required

Request body

This operation has no request body.

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "status": "Not configured",
    "active": false,
    "verified": false,
    "revision": 0,
    "domain": "",
    "records": [],
    "test_status": "not_sent",
    "sandbox": false,
    "draft": null,
    "details": {
      "sender_name": "",
      "sender_email": "",
      "reply_to": [],
      "subject": "Invoice {invoice_number}",
      "body_html": "<p>Your invoice is ready.</p>"
    },
    "provider_ready": true,
    "error": "",
    "deliveries": []
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}
Invoice Email Sender
POST/users/invoice-email-sender

Manage invoice email sender

Updates the account-wide invoice email sender settings using the specified action. Sandbox keys are read-only. Use save_draft to retain setup progress and preview to render a template without sending mail. The save action requires details.sender_name and details.sender_email. Supply reply_to as an array of addresses on the exact sender domain. Templates use details.subject and details.body_html. Verify account DNS proof and sending-domain records before activate. Read the current revision before sender changes, and draft_revision before draft changes. Verification does not activate sending. Optional attachment-free tests go to the verified sender inbox; read test_status before repeating an uncertain test. Document delivery also requires the account’s current email permissions.

API key requiredapplication/json

Request body

FieldTypeRequirement
action

Values: save_draft, preview, save_template, save_active, save, disable, verify, activate, test

stringRequired
revision

Current sender revision; required for verification, activation and tests.

integerOptional
draft_revision

Current draft revision for draft edits.

integerOptional
mode

Values: default, custom

stringOptional
step
integerOptional
details

Sender fields for save, save_active, save_template, save_draft and preview. Templates accept {document_type}, {invoice_number}, {customer_name}, {receiver_name}, {company_name}, {total_amount}, {vat_amount}, {currency}, {invoice_date}.

objectOptional
details.sender_name
stringOptional
details.sender_email
stringOptional
details.subject
stringOptional
details.body_html
stringOptional
details.reply_to
array<string · email>Optional

Responses

200Successful result or business-rule error. Check the boolean status field; status=false indicates failure even when HTTP status is 200.
application/json
{
  "status": true,
  "response": {
    "subject": "Invoice TEST-001",
    "html": "<!doctype html><html><body><p>Your invoice is ready.</p></body></html>"
  }
}
400Invalid request data
application/json
{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}
403API key is missing or invalid
application/json
{
  "status": false,
  "response": "Invalid API key"
}