Documentation Topics

Quick Start Guide Signup & Account Management Free Tenant & Subscriptions Add EGS Unit Reporting Simplified Invoice C# Code Samples of Reporting Api Python Code Samples of Reporting Api Clearing Standard Invoice C# Code Samples of Clearing Api Python Code Samples of Clearing Api Additional Zatca Utiilities Add Customers Download Invoices Subscriptions and License aqusition

Welcome to the system documentation. Select a topic from the sidebar to learn more.

Quick Start

Get up and running quickly with our step-by-step guides.

Get Started

Video Tutorials

Watch our video tutorials to see the system in action.

Watch Videos

Add Customers - Documentation - API Documentation

Customer API Documentation

Overview

This documentation describes how to use the Customer API endpoints to manage customer records in the system. The API requires License Token authentication and automatically associates customers with the tenant making the request.

Authentication

All endpoints require a valid License token with a "TenantId" claim in the Authorization header:

Authorization: Bearer <your-jwt-token>

Endpoints

1. Get All Customers

Endpoint: GET /api/customer

Description: Retrieves a paginated list of customers with optional filtering and sorting.

Query Parameters

Parameter	Type	Description	Example
CusName	string	Filter by customer name (partial match)	`?CusName=John`
CusMobile	string	Filter by mobile number	`?CusMobile=0555555555`
CusType	string	Filter by customer type	`?CusType=B2B`
Email	string	Filter by exact email match	`?Email=test@example.com`
IdNo	string	Filter by ID number	`?IdNo=123456789`
VatNo	string	Filter by VAT number	`?VatNo=300000000000003`
SortBy	string	Field to sort by	`?SortBy=CusName`
IsDescending	bool	Sort in descending order	`?IsDescending=true`
PageNumber	int	Page number (default: 1)	`?PageNumber=2`
PageSize	int	Items per page (default: 10)	`?PageSize=20`

Response

Returns 200 OK with customer list
Includes X-Total-Count header with total number of matching records

Example response body:

[
    {
        "cusId": 1,
        "cusName": "John Doe",
        "cusMobile": "0555555555",
        "cusType": "B2C",
        "idType": "NAT",
        "idNo": "123456789",
        "email": "john@example.com",
        "vatNo": "300000000000003"
    }
]

2. Create Customer

Endpoint: POST /api/customer

Description: Creates a new customer record.

Request Body (application/json)

{
    "cusName": "John Doe",
    "cusMobile": "0555555555",
    "cusType": "B2B",
    "idType": "CRN",
    "idNo": "123456789",
    "bldgNo": "123",
    "street": "Main Street",
    "city": "Riyadh",
    "postalCode": "12345",
    "email": "john@example.com",
    "vatNo": "300000000000003",
    "tinNo": "123456789012345"
}

Validation Rules

vatNo must be 15 characters long, starting and ending with '3'
idType must be one of: TIN, CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, OTH
For B2B customers, postalCode must be exactly 5 characters long
Required fields: idNo, bldgNo, street, city, postalCode

Response

201 Created on success with location header pointing to the new resource
400 Bad Request for validation errors

3. Get Customer by Name

Endpoint: GET /api/customer/{cusName}

Description: Retrieves a single customer by name (exact match).

Response

200 OK with customer data if found
404 Not Found if customer doesn't exist

Example response:

{
    "cusId": 1,
    "cusName": "John Doe",
    "cusMobile": "0555555555",
    "cusType": "B2C",
    "idType": "NAT",
    "idNo": "123456789",
    "email": "john@example.com",
    "vatNo": "300000000000003"
}

4. Update Customer

Endpoint: PUT /api/customer/{CusId}

Description: Updates an existing customer record.

Request Body (application/json)

{
    "cusName": "Updated Name",
    "cusMobile": "0555555555",
    "cusType": "B2B",
    "idType": "CRN",
    "idNo": "123456789",
    "bldgNo": "123",
    "street": "Main Street",
    "city": "Riyadh",
    "postalCode": "12345",
    "email": "updated@example.com",
    "vatNo": "300000000000003",
    "tinNo": "123456789012345"
}

Response

200 OK with updated customer data
400 Bad Request for validation errors
404 Not Found if customer doesn't exist

5. Delete Customer

Endpoint: DELETE /api/customer/{cusName}

Description: Deletes a customer record by name (exact match).

Response

204 No Content on success
404 Not Found if customer doesn't exist

Error Responses

Common error responses include:

400 Bad Request: Invalid input data or validation errors
401 Unauthorized: Missing or invalid License token
404 Not Found: Resource not found
500 Internal Server Error: Server-side error

Sample Usage

First, authenticate to get a License token

Create a customer:

curl -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{
    "cusName": "John Doe",
    "cusMobile": "0555555555",
    "cusType": "B2B",
    "idType": "CRN",
    "idNo": "123456789",
    "bldgNo": "123",
    "street": "Main Street",
    "city": "Riyadh",
    "postalCode": "12345",
    "email": "john@example.com",
    "vatNo": "300000000000003"
}' http://localhost:5000/api/customer

Retrieve customers:

curl -H "Authorization: Bearer <token>" "http://www.pristineinvoice.com/api/customer?CusName=John&PageSize=5"

Note: Replace <token> with your actual License token and adjust the base URL as needed.

Customer onboarding form

You can register any number of customers per your Tenant. but we will advise you to keep frequently accessed customer to the serve need of Walk in Customer

Figure 1: Customer Onboarding Form

Once customer registratio is successfull, you will be navigated to the customer list

Figure 2: Customer List

Add customer Notes:

you can add as many customers as you want.if you want to edit existing customers, you can select the all customers option in the Customers menu

}