Customer
Import Docs

Import Workflow

The page follows a strict linear 3-step flow. Steps 2 and 3 are locked until Step 1 is completed. This prevents accidental uploads without a branch assignment.

Requirements

Server-side dependencies

Client-side dependencies

Step 1 — Branch Select

On page load, loadBranches() is called automatically. It fetches branches from ministry_api.php?action=branches and renders the first 6 as clickable cards plus all branches in a dropdown.

Branch API expected response

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "branch_id":   1,
      "branch_name": "Head Office",
      "branch_code": "HQ-001"
    },
    // ... more branches
  ]
}

State after confirmation

Once the user clicks "Confirm Branch & Continue", the following happens:

• The branch picker is hidden and replaced with a teal summary banner
• Steps 2 and 3 are unlocked (the locked CSS class is removed)
• The branch label in the import action row is updated
• selBranch.branch_id is stored and will be sent as branch_fk on every import POST

Step 2 — Download Template

This step is informational. It provides downloadable templates (CSV and Excel) with the exact column headers the import parser expects. Filling in these templates ensures columns are mapped correctly.

Templates are generated entirely client-side as a blob download — no server call is made.

Step 3 — Upload & Import

Accepted file types

Client-side validation

Before sending any rows to the API, every row is validated in the browser:

Rows with any error are excluded from import but shown in the preview table with a red background and inline error note. The import button shows only the count of valid rows.

Import execution

Each valid row is sent to customer_api.php as a separate POST request. The following fields are always injected regardless of what is in the file:

API Overview

All API endpoints are handled by includes/customer_api.php. Every response follows the same envelope format:

{
  "success": true // or false,
  "message": "Human-readable status",
  "data":    {} // payload or null on error
}

List Customers

Returns a paginated, filterable list of customers. Soft-deleted rows (status = 'Deleted') are excluded by default.

Query parameters

Get Single Customer

Returns a single customer record by primary key.

Create Customer

Creates a new customer. Body must be Content-Type: application/json.

Required fields

Example request

const res = await fetch('includes/customer_api.php', {
  method:  'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    fullname:   "Amina Bello",
    phone:      "08012345678",
    id_type:   "BVN",
    id_number: "12345678901",
    form_type: "PAYROLL",
    branch_fk: 3,
    gender:    "Female",
    employer:  "Federal Polytechnic",
    status:    "Active"
  })
});
const json = await res.json();
// json.data.userid — new customer ID

Response codes

Update Customer

Partial update — only the fields included in the body are changed. The body must be Content-Type: application/json. Any field in ALLOWED_COLUMNS can be updated.

Response codes

Delete Customer

By default, delete is a soft-delete — it sets status = 'Deleted' and updated_at = NOW(). The record remains in the database and can be recovered.

To enable hard deletes, set the constant CUSTOMER_HARD_DELETE = true in customer_api.php. This will issue a real SQL DELETE.

Column Reference

All 22 writeable columns. The userid (primary key) and created_at are auto-generated and cannot be set via the import or API.

Validation Rules

Validation happens in two places: client-side in the browser before import, and server-side in customer_api.php. Both layers apply the same rules.

Error Reference

Column Mapping

The import parser accepts flexible column header names in uploaded files. These are mapped to canonical field names before validation. The mapping is case-insensitive and spaces are converted to underscores.