Differences

This shows you the differences between two versions of the page.

--- api [2025/06/09 15:26] – added "API Reference Guide" dalton
+++ api [2025/11/28 16:22] (current) – API revision as of 28 NOV 25 47.54.102.121
@@ Line 22: / Line 22: @@
   * contacts
   * credentials (logins)
+  * documents
   * domains
+  * expenses
+  * invoices
+  * locations
   * networks
+  * payments
+  * products
+  * quotes
   * software
   * tickets
+  * vendors
@@ Line 65: / Line 73: @@
 ----
+====== API ======
+Use ITFlow's API to work with ITFlow in scripts and third-party applications.
+The current version of the ITFlow API is v1. It can be accessed at **itflow.example.com/api/v1/{module}/{function}.php**
+===== Generating an API Key =====
+  - Login and navigate to the **Admin Settings** page
+  - Select **API Keys**
+  - Select **Create** to open the New Key modal
+  - On Details tab, input the key name and expiration date. Select whether the key will allow access to all clients or a specific client
+  - On Keys tab, note down the API key and credential password and select the checkbox to confirm you've made a copy of the keys. You will not see these again in the admin interface.
+  - Select Create to add the key into the database
+===== Modules with API support =====
+  * assets
+  * certificates
+  * clients
+  * contacts
+  * credentials (logins)
+  * documents
+  * domains
+  * expenses
+  * invoices
+  * locations
+  * networks
+  * payments
+  * products
+  * quotes
+  * software
+  * tickets
+  * vendors
+===== API Functions =====
+  * read
+  * create //(partial - see module details)//
+  * update //(partial - see module details)//
+  * delete //(partial - see module details)//
+  * archive //(clients and contacts only)//
+  * unarchive //(clients and contacts only)//
+  * resolve //(tickets only)//
+===== Request Methods =====
+  * GET - Retrieving (READ) data
+  * POST - Inserting (CREATE), Updating (UPDATE), Deleting (DELETE), or Archiving data
+==== Data Returned ====
+  * Success - True/False
+  * Message - Failure info / Helpful debug info
+  * Count - Count of rows affected/returned
+  * Data - The data requested/created/changed
+==== Notes ====
+  * For read requests, 50 records are shown by default. This can be adjusted by supplying the ''limit'' and ''offset'' parameters.
+  * For POST requests, the ''client_id'' parameter is always required if the API key used has scope/access to all clients
+  * Be sure to check your Apache/PHP error logs if you're running into issues
+----
 ====== API Reference Guide ======
@@ Line 96: / Line 169: @@
 ===== API Overview =====
-**Source**: ITFlow official documentation at docs.itflow.org/api
   * **Base URL**: ''/api/v1/{module}/{function}.php''
@@ Line 108: / Line 179: @@
 ==== Standard Response Format ====
-**Source**: ITFlow official API documentation
 <code json>
@@ Line 120: / Line 189: @@
       "id": 123,
       "field": "value"
+    }
+  ]
+}
+</code>
+==== Create Response Format ====
+<code json>
+{
+  "success": "True",
+  "count": "1",
+  "data": [
+    {
+      "insert_id": 123
     }
   ]
@@ Line 131: / Line 214: @@
   * **Generation**: Admin > API > New Key
   * **Scoping Options**:
-    * **All Clients**: Full access to all client data
+    * **All Clients** (client_id = 0): Full access to all client data
-    * **Specific Client**: Limited to single client (''client_id'' required)
+    * **Specific Client**: Limited to single client data only
-  * **Usage**: Query parameter ''?api_key=YOUR_KEY''
+  * **Usage**: Query parameter ''?api_key=YOUR_KEY'' for GET, or in JSON body for POST
-  * **Security**: Keys stored encrypted in database
+  * **Security**: Keys stored encrypted in database with expiration dates
 ==== Best Practices ====
-**Source**: MSP community recommendations and security standards
   * **Rotate keys** regularly (monthly recommended)
@@ Line 146: / Line 227: @@
   * **Use HTTPS only** for all API calls
-===== Currently Available Modules =====
+----
-**Source**: ITFlow official API documentation confirms these modules have API support:
+===== Module Reference =====
 ==== Assets ''/api/v1/assets/'' ====
@@ Line 154: / Line 235: @@
 **Purpose**: Computer and equipment inventory management
-**Source**: [[https://docs.itflow.org/assets|ITFlow Assets Documentation]]
+**Available Endpoints**:
   * ''GET /read.php'' - List/get asset information
@@ Line 161: / Line 242: @@
   * ''POST /delete.php'' - Delete asset record
-**Complete Fields** (from ITFlow Assets API Documentation):
+**Read Parameters (GET)**:
-<code json>
+^ Parameter ^ Type ^ Description ^
-{
+| asset_id | integer | Get specific asset by ID |
-  "asset_id": 123,
+| asset_type | string | Filter by asset type (auto-capitalized) |
-  "client_id": 456,
+| asset_name | string | Filter by exact asset name |
-  "asset_name": "Sample Laptop",
+| asset_serial | string | Filter by serial number |
-  "asset_type": "Laptop",
+| asset_mac | string | Filter by MAC address (searches primary interface) |
-  "asset_make": "Dell",
+| asset_uri | string | Filter by URI |
-  "asset_model": "Optiplex",
-  "asset_serial": "XYZ",
+**Create/Update Parameters (POST)**:
-  "asset_os": "Win 10",
-  "asset_ip": "",
+^ Parameter ^ Type ^ Required (Create) ^ Description ^
-  "asset_mac": "",
+| api_key | string | Yes | API authentication key |
-  "asset_status": "Deployed",
+| client_id | integer | Yes* | Required if API key has all-client access |
-  "asset_purchase_date": "0000-00-00",
+| asset_name | string | Yes | Asset name/hostname |
-  "asset_warranty_expire": "0000-00-00",
+| asset_description | string | No | Asset description |
-  "install_date": "0000-00-00",
+| asset_type | string | No | Type (Laptop, Desktop, Server, etc.) |
-  "asset_notes": "",
+| asset_make | string | No | Manufacturer |
-  "asset_vendor_id": "",
+| asset_model | string | No | Model name/number |
-  "asset_location_id": "",
+| asset_serial | string | No | Serial number |
-  "asset_contact_id": "",
+| asset_os | string | No | Operating system |
-  "asset_network_id": ""
+| asset_ip | string | No | IP address (stored in primary interface) |
-}
+| asset_mac | string | No | MAC address (stored in primary interface) |
+| asset_uri | string | No | Management URL |
+| asset_status | string | No | Status (Deployed, Spare, etc.) |
+| asset_purchase_date | date | No | Purchase date (YYYY-MM-DD) |
+| asset_warranty_expire | date | No | Warranty expiration date |
+| asset_install_date | date | No | Installation date |
+| asset_notes | string | No | Notes |
+| asset_vendor_id | integer | No | Associated vendor ID |
+| asset_location_id | integer | No | Associated location ID |
+| asset_contact_id | integer | No | Associated contact ID |
+| asset_network_id | integer | No | Network ID for primary interface |
+**Update Additional Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| asset_id | integer | Yes | ID of asset to update |
+**Delete Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| asset_id | integer | Yes | ID of asset to delete |
+<wrap em>Note: Deleting an asset also removes all associated network interfaces.</wrap>
+**Example - Create Asset**:
+<code bash>
+curl -X POST "https://itflow.example.com/api/v1/assets/create.php" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "YOUR_API_KEY",
+    "client_id": 1,
+    "asset_name": "DESKTOP-001",
+    "asset_type": "Desktop",
+    "asset_make": "Dell",
+    "asset_model": "OptiPlex 7090",
+    "asset_serial": "ABC123XYZ",
+    "asset_os": "Windows 11 Pro",
+    "asset_ip": "192.168.1.100",
+    "asset_mac": "00:11:22:33:44:55",
+    "asset_status": "Deployed"
+  }'
 </code>
+----
 ==== Certificates ''/api/v1/certificates/'' ====
@@ Line 191: / Line 315: @@
 **Purpose**: SSL/TLS certificate management and expiration tracking
-**Source**: [[https://docs.itflow.org/certificates|ITFlow Certificates Documentation]]
+**Available Endpoints**:
   * ''GET /read.php'' - List/get certificate information
   * ''POST /create.php'' - Create certificate record
-  * ''POST /update.php'' - Update certificate details
-  * ''POST /delete.php'' - Delete certificate record
-**Complete Fields** (from ITFlow Certificates API Documentation):
+<wrap em>Note: Update and delete endpoints are not implemented.</wrap>
-<code json>
+**Read Parameters (GET)**:
-{
-  "certificate_id": 123,
+^ Parameter ^ Type ^ Description ^
-  "client_id": 456,
+| certificate_id | integer | Get specific certificate by ID |
-  "certificate_name": "ITFlow Demo",
+| certificate_name | string | Filter by certificate name |
-  "certificate_domain": "demo.itflow.org",
-  "certificate_issued_date": "2024-01-01",
+**Create Parameters (POST)**:
-  "certificate_expire_date": "2025-01-01",
-  "certificate_issuer": "Let's Encrypt",
+^ Parameter ^ Type ^ Required ^ Description ^
-  "certificate_public_key": "[Certificate content]",
+| api_key | string | Yes | API authentication key |
-  "certificate_notes": "Auto-renewal enabled"
+| client_id | integer | Yes* | Required if API key has all-client access |
-}
+| certificate_name | string | Yes | Certificate friendly name |
-</code>
+| certificate_domain | string | Yes | Domain the certificate covers |
+| certificate_description | string | No | Description |
+| certificate_issued_by | string | No | Issuing authority (e.g., Let's Encrypt) |
+| certificate_expire | date | No | Expiration date (YYYY-MM-DD) |
+| certificate_public_key | string | No | Certificate content/public key |
+| certificate_notes | string | No | Additional notes |
+| certificate_domain_id | integer | No | Link to domains table |
+----
 ==== Clients ''/api/v1/clients/'' ====
@@ Line 218: / Line 348: @@
 **Purpose**: Customer/company management
-**Source**: [[https://docs.itflow.org/clients|ITFlow Clients Documentation]]
+**Available Endpoints**:
   * ''GET /read.php'' - List/get client information
   * ''POST /create.php'' - Create new client
   * ''POST /update.php'' - Update client details
-  * ''POST /delete.php'' - Delete client record
+  * ''POST /archive.php'' - Archive client
+  * ''POST /unarchive.php'' - Unarchive client
-**Complete Fields** (from ITFlow Clients API Documentation):
+<wrap em>Note: Delete endpoint is not implemented. Use archive instead.</wrap>
-<code json>
+**Read Parameters (GET)**:
-{
-  "client_id": 111,
-  "client_lead": 0,
-  "client_name": "Let it burn Inc",
-  "client_type": "Safety and Fire",
-  "client_website": "example.com"
-}
-</code>
-<wrap em>Note: Full field list is partially documented. The API returns numbered keys alongside named keys in the response format.</wrap>
+^ Parameter ^ Type ^ Description ^
+| client_name | string | Get specific client by exact name |
+**Create Parameters (POST)**:
+<wrap em>Important: Creating clients requires an API key with "All Clients" scope (client_id = 0).</wrap>
+^ Parameter ^ Type ^ Required ^ Description ^
+| api_key | string | Yes | API authentication key (must be all-client scope) |
+| client_name | string | Yes | Client/company name |
+| client_type | string | No | Business type/category |
+| client_website | string | No | Website URL (https:// prefix auto-removed) |
+| client_referral | string | No | Referral source |
+| client_rate | decimal | No | Hourly rate |
+| client_currency_code | string | No | Currency code (e.g., USD) |
+| client_net_terms | integer | No | Payment terms in days |
+| client_tax_id_number | string | No | Tax ID/EIN |
+| client_abbreviation | string | No | Short code (max 6 chars) |
+| client_is_lead | integer | No | Lead flag (0 or 1) |
+| client_notes | string | No | Additional notes |
+**Update Additional Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| client_id | integer | Yes | ID of client to update |
+**Archive/Unarchive Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| client_id | integer | Yes | ID of client (from API key scope) |
+<wrap em>Note: Archiving a client automatically stops all recurring invoices for that client.</wrap>
+----
 ==== Contacts ''/api/v1/contacts/'' ====
@@ Line 243: / Line 399: @@
 **Purpose**: Individual contact management within client organizations
-**Source**: ITFlow official API documentation lists contacts as supported module
+**Available Endpoints**:
   * ''GET /read.php'' - List/get contact information
@@ Line 249: / Line 405: @@
   * ''POST /update.php'' - Update contact details
   * ''POST /delete.php'' - Delete contact record
+  * ''POST /archive.php'' - Archive contact
+  * ''POST /unarchive.php'' - Unarchive contact
-**Available Fields**: Contact table structure includes fields like ''contact_department'' as confirmed by GitHub Issue #458, but complete API field specification is not fully documented.
+**Read Parameters (GET)**:
+^ Parameter ^ Type ^ Description ^
+| contact_id | integer | Get specific contact by ID |
+| contact_email | string | Get contact by email address |
+| contact_phone_or_mobile | string | Get contact by phone or mobile number |
+**Create Parameters (POST)**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| api_key | string | Yes | API authentication key |
+| client_id | integer | Yes* | Required if API key has all-client access |
+| contact_name | string | Yes | Full name |
+| contact_email | string | Yes | Email address (must be unique per client) |
+| contact_title | string | No | Job title |
+| contact_department | string | No | Department |
+| contact_phone | string | No | Phone number (non-digits stripped) |
+| contact_extension | string | No | Phone extension |
+| contact_mobile | string | No | Mobile number (non-digits stripped) |
+| contact_notes | string | No | Notes |
+| contact_primary | integer | No | Primary contact flag (0 or 1) |
+| contact_important | integer | No | Important flag (0 or 1) |
+| contact_billing | integer | No | Billing contact flag (0 or 1) |
+| contact_technical | integer | No | Technical contact flag (0 or 1) |
+| contact_location_id | integer | No | Associated location ID |
+<wrap em>Note: Setting contact_primary = 1 will remove primary flag from other contacts for that client.</wrap>
+**Update Additional Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| contact_id | integer | Yes | ID of contact to update |
+**Delete Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| contact_id | integer | Yes | ID of contact to delete |
+**Archive/Unarchive Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| contact_id | integer | Yes | ID of contact to archive/unarchive |
+<wrap em>Note: Archiving a contact also archives their associated user account if one exists.</wrap>
+----
 ==== Credentials ''/api/v1/credentials/'' ====
@@ Line 256: / Line 459: @@
 **Purpose**: Password and login management (encrypted storage)
-**Source**: ITFlow official API documentation lists credentials (logins) as supported module
+**Available Endpoints**:
   * ''GET /read.php'' - List/get credential information
   * ''POST /create.php'' - Create new credential record
   * ''POST /update.php'' - Update credential details
-  * ''POST /delete.php'' - Delete credential record
-**Available Fields**: Database migration scripts confirm ''login_folder_id'' field addition, but complete API field specification requires further documentation.
+<wrap em>Note: Delete endpoint is not implemented.</wrap>
+<wrap em>Important: The ''api_key_decrypt_password'' parameter is required for ALL credential operations.</wrap>
+**Read Parameters (GET)**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| api_key_decrypt_password | string | Yes | Decryption password for the API key |
+| credential_id | integer | No | Get specific credential by ID |
+**Create Parameters (POST)**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| api_key | string | Yes | API authentication key |
+| api_key_decrypt_password | string | Yes | Decryption password |
+| client_id | integer | Yes* | Required if API key has all-client access |
+| credential_name | string | Yes | Credential name/label |
+| credential_password | string | Yes | Password (will be encrypted) |
+| credential_description | string | No | Description |
+| credential_uri | string | No | Login URL |
+| credential_uri_2 | string | No | Secondary URL |
+| credential_username | string | No | Username (will be encrypted) |
+| credential_otp_secret | string | No | TOTP/2FA secret |
+| credential_note | string | No | Additional notes |
+| credential_important | integer | No | Important flag (0 or 1) |
+| credential_contact_id | integer | No | Associated contact ID |
+| credential_vendor_id | integer | No | Associated vendor ID |
+| credential_asset_id | integer | No | Associated asset ID |
+| credential_software_id | integer | No | Associated software ID |
+**Update Additional Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| credential_id | integer | Yes | ID of credential to update |
+| api_key_decrypt_password | string | Yes | Decryption password |
+<wrap em>Note: Updating the password field automatically updates the password_changed_at timestamp.</wrap>
+----
+==== Documents ''/api/v1/documents/'' ====
+**Purpose**: Internal documentation and knowledge base articles
+**Available Endpoints**:
+  * ''GET /read.php'' - List/get document information
+  * ''POST /create.php'' - Create new document
+  * ''POST /update.php'' - Update document
+<wrap em>Note: Delete endpoint is not implemented.</wrap>
+**Read Parameters (GET)**:
+^ Parameter ^ Type ^ Description ^
+| document_id | integer | Get specific document by ID |
+**Create Parameters (POST)**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| api_key | string | Yes | API authentication key |
+| client_id | integer | Yes* | Required if API key has all-client access |
+| document_name | string | Yes | Document title |
+| document_content | string | Yes | Document content (HTML supported) |
+| document_description | string | No | Brief description |
+| document_folder_id | integer | No | Folder ID for organization |
+**Update Additional Parameters**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| document_id | integer | Yes | ID of document to update |
+----
 ==== Domains ''/api/v1/domains/'' ====
@@ Line 269: / Line 543: @@
 **Purpose**: Domain name management and renewal tracking
-**Source**: [[https://docs.itflow.org/domains|ITFlow Domains Documentation]]
+**Available Endpoints**:
   * ''GET /read.php'' - List/get domain information
-  * ''POST /create.php'' - Create domain record
-  * ''POST /update.php'' - Update domain details
-  * ''POST /delete.php'' - Delete domain record
-**Complete Fields** (from ITFlow Domains API Documentation):
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
-<code json>
+**Read Parameters (GET)**:
-{
-  "domain_id": 123,
+^ Parameter ^ Type ^ Description ^
-  "client_id": 456,
+| domain_id | integer | Get specific domain by ID |
-  "domain_name": "itflow.org",
+| domain_name | string | Get domain by exact name |
-  "domain_registrar": "GoDaddy",
-  "domain_webhost": "SiteGround",
+**Response Fields**:
-  "domain_expire": "2025-03-15",
-  "domain_ip": "192.168.1.1",
+^ Field ^ Type ^ Description ^
-  "domain_name_servers": "ns1.example.com, ns2.example.com",
+| domain_id | integer | Primary key |
-  "domain_mail_servers": "mx1.example.com",
+| domain_name | string | Domain name |
-  "domain_notes": "Auto-renewal enabled"
+| domain_description | string | Description |
-}
+| domain_expire | date | Expiration date |
-</code>
+| domain_ip | string | IP address(es) |
+| domain_name_servers | string | Name servers |
+| domain_mail_servers | string | MX records |
+| domain_txt | string | TXT records |
+| domain_raw_whois | string | Raw WHOIS data |
+| domain_notes | string | Notes |
+| domain_registrar | integer | Registrar vendor ID |
+| domain_webhost | integer | Web host vendor ID |
+| domain_dnshost | integer | DNS host vendor ID |
+| domain_mailhost | integer | Mail host vendor ID |
+| domain_client_id | integer | Client ID |
+----
+==== Expenses ''/api/v1/expenses/'' ====
+**Purpose**: Track business expenses
+**Available Endpoints**:
+  * ''GET /read.php'' - List/get expense information
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
+<wrap em>Important: Expenses require an API key with "All Clients" scope.</wrap>
+**Read Parameters (GET)**:
+^ Parameter ^ Type ^ Description ^
+| expense_id | integer | Get specific expense by ID |
+----
+==== Invoices ''/api/v1/invoices/'' ====
+**Purpose**: Access invoice records
+**Available Endpoints**:
+  * ''GET /read.php'' - List/get invoice information
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
+**Read Parameters (GET)**:
+^ Parameter ^ Type ^ Description ^
+| invoice_id | integer | Get specific invoice by ID |
+----
+==== Locations ''/api/v1/locations/'' ====
+**Purpose**: Manage client office/site locations
+**Available Endpoints**:
+  * ''GET /read.php'' - List/get location information
+  * ''POST /create.php'' - Create new location
+<wrap em>Note: Update and delete endpoints are not implemented.</wrap>
+**Read Parameters (GET)**:
+^ Parameter ^ Type ^ Description ^
+| location_id | integer | Get specific location by ID |
+**Create Parameters (POST)**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| api_key | string | Yes | API authentication key |
+| client_id | integer | Yes* | Required if API key has all-client access |
+| location_name | string | Yes | Location name |
+| location_description | string | No | Description |
+| location_country | string | No | Country |
+| location_address | string | No | Street address |
+| location_city | string | No | City |
+| location_state | string | No | State/province |
+| location_zip | string | No | ZIP/postal code |
+| location_hours | string | No | Business hours |
+| location_notes | string | No | Notes |
+| location_primary | integer | No | Primary location flag (0 or 1) |
+<wrap em>Note: Setting location_primary = 1 will remove primary flag from other locations for that client.</wrap>
+----
 ==== Networks ''/api/v1/networks/'' ====
@@ Line 297: / Line 652: @@
 **Purpose**: Network infrastructure documentation
-**Source**: ITFlow official API documentation lists networks as supported module
+**Available Endpoints**:
   * ''GET /read.php'' - List/get network information
-  * ''POST /create.php'' - Create network record
-  * ''POST /update.php'' - Update network details
-  * ''POST /delete.php'' - Delete network record
-**Available Fields**: Database migration scripts show network interface relationships, but complete API field specification requires further documentation.
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
-==== Software ''/api/v1/software/'' ====
+**Read Parameters (GET)**:
-**Purpose**: Software license and application tracking
+^ Parameter ^ Type ^ Description ^
+| network_id | integer | Get specific network by ID |
+| network_name | string | Get network by exact name |
-**Source**: ITFlow official API documentation lists software as supported module
+----
-  * ''GET /read.php'' - List/get software information
+==== Payments ''/api/v1/payments/'' ====
-  * ''POST /create.php'' - Create software record
-  * ''POST /update.php'' - Update software details
-  * ''POST /delete.php'' - Delete software record
-**Status**: Module confirmed as available but dedicated documentation page not found. Database includes software table as confirmed by installation scripts.
+**Purpose**: Access payment records
-==== Tickets ''/api/v1/tickets/'' ====
+**Available Endpoints**:
-**Purpose**: Help desk and issue tracking
+  * ''GET /read.php'' - List/get payment information
-**Source**: [[https://docs.itflow.org/tickets|ITFlow Tickets Documentation]]
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
-  * ''GET /read.php'' - List/get ticket information
+<wrap em>Important: Payments require an API key with "All Clients" scope.</wrap>
-  * ''POST /create.php'' - Create new ticket
-  * ''POST /update.php'' - Update ticket details
-  * ''POST /delete.php'' - Delete ticket record
-**Complete Fields** (from ITFlow Tickets API Documentation):
+**Read Parameters (GET)**:
-<code json>
+^ Parameter ^ Type ^ Description ^
-{
+| payment_id | integer | Get specific payment by ID |
-  "ticket_id": 3,
+| payment_invoice_id | integer | Get all payments for an invoice |
-  "ticket_prefix": "TCK-",
-  "ticket_number": 3,
-  "ticket_category": null,
-  "ticket_subject": "Computer broken"
-}
-</code>
-<wrap em>Note: Full field list is partially documented. The API returns numbered keys alongside named keys in the response format.</wrap>
+----
-===== Current API Capabilities =====
+==== Products ''/api/v1/products/'' ====
-==== Standard Operations (All Modules) ====
+**Purpose**: Access product/service catalog
-  * **READ**: Retrieve single record or list of records
+**Available Endpoints**:
-  * **CREATE**: Add new records with validation (partial support)
-  * **UPDATE**: Modify existing records (partial support)
-  * **DELETE**: Remove records (partial support)
-==== Query Parameters (read.php endpoints) ====
+  * ''GET /read.php'' - List/get product information
-  * ''client_id'' - Filter by specific client
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
-  * ''limit'' - Number of records to return (default: 50)
-  * ''offset'' - Number of records to skip for pagination
-  * API key required on all requests
-==== Response Format (Standardized) ====
+<wrap em>Important: Products require an API key with "All Clients" scope.</wrap>
-<code json>
+**Read Parameters (GET)**:
-{
-  "success": "True|False",
-  "message": "Descriptive message",
-  "count": 1,
-  "data": [
-    {
-      // Record data with both numbered and named keys
-    }
-  ]
-}
-</code>
-===== Current Authentication =====
+^ Parameter ^ Type ^ Description ^
+| product_id | integer | Get specific product by ID |
-==== API Key Generation ====
+----
-  - Navigate to Admin panel in ITFlow
+==== Quotes ''/api/v1/quotes/'' ====
-  - Click on API section
-  - Click **New Key** to generate
-  - Choose scope: specific client or all clients
-  - Copy generated key for use
-==== API Key Usage ====
+**Purpose**: Access sales quote records
-  * **Method**: Query parameter
+**Available Endpoints**:
-  * **Format**: ''?api_key=YOUR_API_KEY''
-  * **Scope**: Can be limited to specific client or all clients
-  * **Access**: Currently all-or-nothing permissions
-==== Security Features ====
+  * ''GET /read.php'' - List/get quote information
-  * **Encrypted Storage**: API keys stored securely
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
-  * **Client Scoping**: Keys can be limited to specific clients
-  * **Access Logging**: API usage tracked in logs
-===== Current Limitations =====
+**Read Parameters (GET)**:
-==== Missing CRUD Operations ====
+^ Parameter ^ Type ^ Description ^
+| quote_id | integer | Get specific quote by ID |
-  * **UPDATE**: Limited support across modules
+----
-  * **DELETE**: Limited support across modules
-  * **ARCHIVE**: Not implemented
-==== Missing Advanced Features ====
+==== Software ''/api/v1/software/'' ====
-  * **Bulk Operations**: No batch create/update/delete
+**Purpose**: Software license and application tracking
-  * **Advanced Search**: No full-text search or complex filtering
-  * **Webhooks**: No real-time event notifications
-  * **File Upload**: No direct file management API
-  * **Relationships**: Limited cross-module data retrieval
-==== Missing Business Modules ====
+**Available Endpoints**:
-  * **Invoices/Billing**: No financial transaction APIs
+  * ''GET /read.php'' - List/get software information
-  * **Quotes**: No sales proposal management
-  * **Time Tracking**: No billable hour recording
-  * **Calendar**: No scheduling or appointment APIs
-  * **Reports**: No automated report generation
-==== Authentication Limitations ====
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
-  * **Granular Permissions**: No module-specific access control
+**Read Parameters (GET)**:
-  * **OAuth**: Only API key authentication available
-===== API Usage Examples =====
+^ Parameter ^ Type ^ Description ^
+| software_id | integer | Get specific software by ID |
+| software_name | string | Get by exact name |
+| software_type | string | Filter by type |
-==== Get All Clients ====
+----
-<code bash>
+==== Tickets ''/api/v1/tickets/'' ====
-GET /api/v1/clients/read.php?api_key=YOUR_KEY
-</code>
-==== Get Specific Asset ====
+**Purpose**: Help desk and issue tracking
-<code bash>
+**Available Endpoints**:
-GET /api/v1/assets/read.php?api_key=YOUR_KEY&asset_id=123
-</code>
-==== Create New Ticket ====
+  * ''GET /read.php'' - List/get ticket information
+  * ''POST /create.php'' - Create new ticket
+  * ''POST /resolve.php'' - Resolve/close ticket
-<code bash>
+<wrap em>Note: Update and delete endpoints are not implemented.</wrap>
-POST /api/v1/tickets/create.php
-Content-Type: application/json
-{
+**Read Parameters (GET)**:
-  "api_key": "YOUR_KEY",
-  "client_id": 456,
-  "ticket_subject": "Printer offline",
-  "ticket_details": "Office printer not responding",
-  "ticket_priority": "Medium"
-}
-</code>
-==== List Client Assets ====
+^ Parameter ^ Type ^ Description ^
+| ticket_id | integer | Get specific ticket by ID (includes status information) |
+**Create Parameters (POST)**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| api_key | string | Yes | API authentication key |
+| client_id | integer | No | Client ID (defaults to 0 if not provided) |
+| ticket_subject | string | Yes | Ticket subject/title |
+| ticket_details | string | No | Ticket description |
+| ticket_priority | string | No | Priority (Low, Medium, High) - defaults to "Low" |
+| ticket_contact_id | integer | No | Contact ID (auto-selects primary contact if not provided) |
+| ticket_asset_id | integer | No | Related asset ID |
+| ticket_vendor_id | integer | No | Escalation vendor ID |
+| ticket_vendor_ticket_id | integer | No | Vendor's ticket number |
+| ticket_assigned_to | integer | No | Assigned user ID |
+| ticket_billable | integer | No | Billable flag (0 or 1) |
+<wrap em>Note: Ticket number is auto-generated based on system settings. Ticket source is set to "API".</wrap>
+**Resolve Parameters (POST)**:
+^ Parameter ^ Type ^ Required ^ Description ^
+| ticket_id | integer | Yes | ID of ticket to resolve |
+<wrap em>Note: Resolving sets status to Resolved and records the resolution timestamp. Also sets first response time if not already set.</wrap>
+**Example - Create Ticket**:
 <code bash>
-GET /api/v1/assets/read.php?api_key=YOUR_KEY&client_id=456
+curl -X POST "https://itflow.example.com/api/v1/tickets/create.php" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "YOUR_API_KEY",
+    "client_id": 456,
+    "ticket_subject": "Printer offline",
+    "ticket_details": "Office printer not responding to print jobs",
+    "ticket_priority": "Medium"
+  }'
 </code>
-===== Integration Capabilities =====
+----
-==== What Works Today ====
+==== Vendors ''/api/v1/vendors/'' ====
-  * **Basic CRUD**: Create/read operations for core modules
+**Purpose**: Manage vendor/supplier records
-  * **Client Management**: Full customer database management
-  * **Asset Tracking**: Computer and equipment inventory
-  * **Ticket Creation**: Help desk ticket automation
-  * **Documentation**: Network, domain, certificate tracking
-==== What's Missing for Full Automation ====
+**Available Endpoints**:
-  * **Financial Operations**: No billing/invoicing automation
+  * ''GET /read.php'' - List/get vendor information
-  * **Real-time Events**: No webhook triggers for automation
-  * **Bulk Data Sync**: No efficient mass data operations
-  * **File Management**: No document upload/download APIs
-  * **Advanced Workflows**: No time tracking or scheduling APIs
-===== Error Handling & Troubleshooting =====
+<wrap em>Note: Create, update, and delete endpoints are not implemented.</wrap>
-==== Standard Error Codes ====
+**Read Parameters (GET)**:
-**Source**: HTTP standard codes - ITFlow API observed behavior
+^ Parameter ^ Type ^ Description ^
+| vendor_id | integer | Get specific vendor by ID |
-  * **200**: Success - Request completed successfully
+----
-  * **400**: Bad Request - Invalid parameters or malformed request
-  * **401**: Unauthorized - Invalid or missing API key
-  * **403**: Forbidden - API key lacks required permissions
-  * **404**: Not Found - Endpoint or record doesn't exist
-  * **500**: Server Error - Internal ITFlow error
-==== Common Error Messages ====
+===== Custom API Extensions =====
-**Source**: Observed API responses
+**Location**: ''/api/v1/custom/''
-<code json>
+ITFlow supports custom API endpoints. Place custom PHP files in the ''custom'' directory to extend API functionality.
-{
-  "success": "False",
-  "message": "Invalid API key",
-  "count": 0,
-  "data": []
-}
-</code>
-==== Troubleshooting Steps ====
+----
-**Source**: Community experience and [[https://docs.itflow.org/installation|ITFlow Installation Documentation]]
+===== Error Handling & Troubleshooting =====
+==== HTTP Status Codes ====
+^ Code ^ Description ^
+| 200 | Success - Request completed successfully |
+| 401 | Unauthorized - Invalid or missing API key |
+| 405 | Method Not Allowed - Only GET and POST supported |
+==== Common Error Messages ====
+^ Message ^ Cause ^
+| "Authentication failed. API key is invalid or has expired." | Invalid or expired API key |
+| "No resource (for this client and company) with the specified parameter(s)." | Record not found or access denied |
+| "Auth success but insert query failed..." | Missing required fields or duplicate data |
+| "Auth success but update query failed..." | Invalid ID or no matching record |
+| "Auth success but delete query failed..." | Invalid ID or client mismatch |
+==== Troubleshooting Steps ====
   - **API Key Issues**
     * Verify key is correct (copy/paste errors common)
     * Check key scope (client-specific vs all clients)
-    * Confirm key hasn't been deactivated
+    * Confirm key hasn't expired
   - **Permission Errors**
@@ Line 528: / Line 861: @@
     * Check data types (strings, integers, dates)
     * Verify foreign key relationships exist
+    * Ensure unique constraints aren't violated (e.g., contact email per client)
-==== Debug Mode ====
+----
-**Source**: ITFlow admin settings and [[https://docs.itflow.org/faq|ITFlow FAQ]]
-Enable PHP error reporting in ITFlow settings for detailed error messages during development.
 ===== Integration Examples =====
-==== PowerShell Examples ====
+==== PowerShell ====
-**Source**: [[https://github.com/itflow-org/itflow-api-powershell|ITFlow PowerShell Repository]]
 **List All Clients**:
@@ Line 560: / Line 888: @@
     "asset_type" = "Laptop"
     "asset_make" = "Dell"
-    "asset_model" = "Optiplex"
+    "asset_model" = "Latitude 5520"
     "client_id" = "1"
 } | ConvertTo-Json
@@ Line 567: / Line 895: @@
 </code>
-==== PHP Examples ====
+==== Python ====
-<code php>
-<?php
-$api_key = 'YOUR_API_KEY';
-$base_url = 'https://itflow.yourdomain.com/api/v1/';
-// Get clients
-$url = $base_url . 'clients/read.php?api_key=' . $api_key;
-$response = file_get_contents($url);
-$data = json_decode($response, true);
-print_r($data);
-?>
-</code>
-==== Python Examples ====
 <code python>
@@ Line 609: / Line 921: @@
 print(result)
 </code>
+==== PHP ====
+<code php>
+<?php
+$api_key = 'YOUR_API_KEY';
+$base_url = 'https://itflow.yourdomain.com/api/v1/';
+// Get clients
+$url = $base_url . 'clients/read.php?api_key=' . $api_key;
+$response = file_get_contents($url);
+$data = json_decode($response, true);
+print_r($data);
+?>
+</code>
+==== cURL ====
+<code bash>
+# Get all assets for a client
+curl "https://itflow.example.com/api/v1/assets/read.php?api_key=YOUR_KEY&limit=10"
+# Create a contact
+curl -X POST "https://itflow.example.com/api/v1/contacts/create.php" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "YOUR_KEY",
+    "client_id": 1,
+    "contact_name": "John Smith",
+    "contact_email": "john@example.com",
+    "contact_phone": "5551234567",
+    "contact_primary": 1
+  }'
+</code>
+----
+===== API Module Summary =====
+^ Module ^ Read ^ Create ^ Update ^ Delete ^ Archive ^ Other ^
+| Assets | ✓ | ✓ | ✓ | ✓ | - | - |
+| Certificates | ✓ | ✓ | - | - | - | - |
+| Clients | ✓ | ✓ | ✓ | - | ✓ | unarchive |
+| Contacts | ✓ | ✓ | ✓ | ✓ | ✓ | unarchive |
+| Credentials | ✓ | ✓ | ✓ | - | - | - |
+| Documents | ✓ | ✓ | ✓ | - | - | - |
+| Domains | ✓ | - | - | - | - | - |
+| Expenses | ✓ | - | - | - | - | - |
+| Invoices | ✓ | - | - | - | - | - |
+| Locations | ✓ | ✓ | - | - | - | - |
+| Networks | ✓ | - | - | - | - | - |
+| Payments | ✓ | - | - | - | - | - |
+| Products | ✓ | - | - | - | - | - |
+| Quotes | ✓ | - | - | - | - | - |
+| Software | ✓ | - | - | - | - | - |
+| Tickets | ✓ | ✓ | - | - | - | resolve |
+| Vendors | ✓ | - | - | - | - | - |

Tools

menus and quick search

quick search

site status

location indicator

Page Tools

meta data for this page

Differences