# Aiwyn API

# Welcome to Aiwyn API

The Aiwyn API provides programmatic access to our comprehensive suite of financial automation tools.
Build powerful integrations and automate your accounting workflows with our RESTful APIs.

## Key Features

- 🔐 **Secure Authentication** - Industry-standard OAuth 2.0 and API key authentication
- 📊 **Real-time Data** - Access up-to-date financial information
- 🚀 **High Performance** - Low latency, high throughput API infrastructure
- 📚 **Comprehensive Coverage** - Full access to clients, engagements, expenses, and more
- 🛠️ **Developer-Friendly** - Extensive documentation, SDKs, and code examples

## API Versioning

We use URL versioning for our APIs. The current version is `v1`. All endpoints are prefixed with the version number.


Version: 1.0.0

## Servers

Staging Environment (Test Data)
```
https://demo.api.aiwyn.ai
```

## Security

### BearerAuth

Firebase JWT Bearer token authentication with Hasura integration for user-based access.

**Usage:**
```
Authorization: Bearer <jwt-token>
```

**Token Requirements:**
- JWT tokens are issued by Firebase Authentication (Google Secure Token Service)
- Tokens contain Hasura role-based permissions and tenant context
- Standard expiration time: 1 hour (3600 seconds)
- Supports SAML/Google identity providers
- Contains both application roles and Hasura-specific claims

**Token Structure:**
```json
{
  "https://hasura.io/jwt/claims": {
    "x-hasura-allowed-roles": [
      "aiwynsb_SUPER_ADMIN",
      "aiwynsb_API_USER", 
      "aiwynsb_API_ADMIN"
    ],
    "x-hasura-default-role": "aiwynsb_API_ADMIN"
  },
  "staffId": 420,
  "tenant": "aiwynsb",
  "roles": ["SUPER_ADMIN", "aiwynsb_API_ADMIN"],
  "email": "user@aiwyn.ai",
  "authKeyId": 11,
  "iss": "https://securetoken.google.com/an-staging-302521",
  "aud": "an-staging-302521",
  "auth_time": 1758777932,
  "user_id": "ocGkQDCe0MgLudgrjR18h5oKuVE2",
  "sub": "ocGkQDCe0MgLudgrjR18h5oKuVE2",
  "iat": 1758777932,
  "exp": 1758781532,
  "email_verified": true,
  "firebase": {
    "identities": {
      "saml.google": ["user@aiwyn.ai"],
      "email": ["user@aiwyn.ai"]
    },
    "sign_in_provider": "custom",
    "tenant": "aiwynsandbox-firm-o64vu"
  }
}
```

**Example:**
```bash
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     https://api.yourdomain.com/v1/clients
```


Type: http
Scheme: bearer
Bearer Format: JWT

### SecurityHeaders

Additional security headers that may be required or optional
depending on the authentication method and tenant configuration.


Type: object

## Download OpenAPI description

[Aiwyn API](https://api.doc.aiwyn.ai/_bundle/bundle.yaml)

## 🔐 Authentication

Authentication endpoints for obtaining access tokens and managing API keys.


### Generate API Token

 - [POST /v1/auth/token](https://api.doc.aiwyn.ai/bundle/authentication/generateapitoken.md): Exchange an jwt Api Key to generate an API Token for accessing
Product APIs.

## 👤 Client

Manage client records, profiles, and related operations.


### List clients

 - [POST /gql/v1/clients](https://api.doc.aiwyn.ai/bundle/client/getclients.md): Retrieve all clients with basic pagination support

This endpoint provides simple client listing capabilities without any filtering restrictions.
It's designed for scenarios where you need to browse through the entire client database
with standard pagination controls.

Key Features:
- Basic pagination with configurable page sizes (default: 50 records)
- Default sorting by client name (ascending) then creation date (descending)  
- Complete client information including contact details and staff assignments
- Total count aggregation for pagination metadata
- No filtering logic - returns all clients in the system
- Optimized for dashboard displays and data export operations

Performance Considerations:
- Default 50-record pageSize prevents memory issues with large datasets
- Indexed sorting on name and createdAt fields for optimal query performance
- Consider using filtered queries for large client databases (1000+ records)
- Suitable for datasets up to 10,000 clients with reasonable response times

Real Example:
bash
curl --location 'https://{{host}}/v1/clients' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search clients

 - [POST /gql/v1/clients/search](https://api.doc.aiwyn.ai/bundle/client/filterclientsdynamic.md): Advanced client filtering with custom GraphQL where clauses and dynamic ordering

This query provides maximum flexibility for client data retrieval through custom
GraphQL-style where clause construction and dynamic ordering specifications.
It's designed for complex business requirements that need sophisticated filtering logic.

Key Features:
- Custom GraphQL where clause construction for unlimited filtering combinations
- Dynamic order_by specifications supporting multi-field sorting with custom directions
- Advanced boolean logic combining multiple filter conditions with _and, _or, _not
- Relationship-based filtering across connected entities (contacts, staff assignments)
- Custom pagination with flexible pageSize and page controls for any result set size
- Full access to GraphQL query capabilities through REST interface abstraction
- Enterprise-grade filtering supporting complex business logic requirements
- Support for nested queries and conditional logic patterns

Advanced Filtering Capabilities:
- Boolean Logic: _and, _or, _not operators for complex condition combinations
- Text Operations: _like, _ilike, _regex for pattern matching and search
- Comparison Operators: _gt, _gte, _lt, _lte, _eq, _neq for numerical/date comparisons  
- Array Operations: _in, _nin for multi-value filtering and inclusion/exclusion
- Null Handling: _is_null for empty value detection and filtering
- Relationship Traversal: Filter on connected entities like contacts and staff
- Date Ranges: Precision timestamp filtering for time-based analysis
- Case Sensitivity: Both case-sensitive and case-insensitive text matching

Dynamic Ordering Options:
- Multi-field Sorting: Order by multiple columns with individual sort directions
- Relationship Sorting: Sort by connected entity fields (staff names, contact info)
- Custom Directions: Mix ascending and descending order across different fields
- Priority Ordering: Define primary, secondary, tertiary sort criteria
- Date-based Sorting: createdAt, updatedAt for chronological ordering
- Text Sorting: Alphabetical ordering with locale-aware collation

Real Example:
bash
curl --location 'https://{{host}}/v1/clients/search' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "name": {
              "_ilike": "%tech%"
            }
          },
          {
            "clientRef": {
              "_ilike": "%45%"
            }
          }
        ]
      },
      {
        "active": {
          "_eq": true
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "partnerStaffId": {
          "_in": [
            5,
            6,
            7,
            8
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "name": "asc"
    },
    {
      "createdAt": "desc"
    }
  ]
}'

### Get client by ID

 - [GET /gql/v1/client/{id}](https://api.doc.aiwyn.ai/bundle/client/getclientbyid.md): Retrieve a specific client by its unique identifier

This endpoint provides detailed client information including:
- Complete client details and demographics
- Client status and relationship information
- Contact and address information
- Engagement and project portfolio
- Financial and billing information
- Industry and business classification

Client Management Features:
- Client lifecycle tracking
- Relationship management
- Contact and address management
- Engagement portfolio oversight
- Financial and billing setup

Client Details Include:
- Client name and demographics
- Client status and type
- Contact information
- Address and location
- Engagement portfolio
- Financial information

Business Applications:
- Client relationship management
- Engagement portfolio analysis
- Financial performance tracking
- Contact management
- Business development planning

Real Example:
bash
curl --location 'https://{{host}}/v1/client/789' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 789,
  "name": "Acme Corporation",
  "legalName": "Acme Corporation, Inc.",
  "status": "ACTIVE",
  "type": "CORPORATE",
  "industry": "MANUFACTURING",
  "size": "LARGE",
  "website": "https://www.acme.com",
  "taxId": "12-3456789",
  "phone": "+1-555-0123",
  "email": "info@acme.com",
  "address": {
    "street": "123 Business Ave",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "billingAddress": {
    "street": "456 Finance Blvd",
    "city": "New York",
    "state": "NY",
    "zipCode": "10002",
    "country": "USA"
  },
  "primaryContact": {
    "id": 23456,
    "name": "John Smith",
    "title": "Chief Financial Officer",
    "email": "john.smith@acme.com",
    "phone": "+1-555-0123"
  },
  "engagements": [
    {
      "id": 34567,
      "name": "Annual Audit Engagement 2024",
      "status": "ACTIVE",
      "type": "AUDIT",
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z"
    }
  ],
  "financialSummary": {
    "totalRevenue": 150000.00,
    "outstandingBalance": 25000.00,
    "currency": "USD",
    "lastPaymentDate": "2024-11-15T10:30:00Z"
  },
  "notes": "Long-term client with excellent payment history and strong relationship",
  "createdAt": "2020-01-15T10:00:00Z",
  "updatedAt": "2024-11-20T14:30:00Z"
}

## 📇 Contact

Manage contact information and relationships for clients.


### List contacts

 - [POST /gql/v1/contacts](https://api.doc.aiwyn.ai/bundle/contact/getcontactspaginated.md): Retrieve all contacts with basic pagination support

Returns a paginated list of contacts. Default sort prioritizes last/first name.

Real Example:
bash
curl --location 'https://{{host}}/v1/contacts' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search contacts

 - [POST /gql/v1/contacts/search](https://api.doc.aiwyn.ai/bundle/contact/filtercontactsdynamic.md): Advanced contact filtering with custom GraphQL where clauses and dynamic ordering

Filter contacts using boolean logic and relationship-aware fields from contact_info.

Real Example:
bash
curl --location 'https://{{host}}/v1/contacts/search' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "contact_info": {
              "firstName": {
                "_ilike": "%john%"
              }
            }
          },
          {
            "contact_info": {
              "lastName": {
                "_ilike": "%doe%"
              }
            }
          }
        ]
      },
      {
        "active": {
          "_eq": true
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "contact_info": {
          "email": {
            "_ilike": "%@company.com%"
          }
        }
      }
    ]
  },
  "orderBy": [
    {
      "contact_info": {
        "lastName": "asc"
      }
    },
    {
      "createdAt": "desc"
    }
  ]
}'

### Get contact by ID

 - [GET /gql/v1/contact/{id}](https://api.doc.aiwyn.ai/bundle/contact/getcontactbyid.md): Retrieve a specific contact by its unique identifier

This endpoint provides detailed contact information including:
- Complete contact details and demographics
- Contact status and relationship information
- Client associations and roles
- Communication preferences and history
- Address and location information
- Professional and personal details

Contact Management Features:
- Contact lifecycle tracking
- Client relationship management
- Communication preference management
- Address and location tracking
- Professional information management

Contact Details Include:
- Contact name and demographics
- Contact status and type
- Client associations
- Communication preferences
- Address information
- Professional details

Business Applications:
- Contact relationship management
- Client communication planning
- Contact database maintenance
- Professional network management
- Communication preference tracking

Real Example:
bash
curl --location 'https://{{host}}/v1/contact/23456' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 23456,
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@acme.com",
  "phone": "+1-555-0123",
  "mobile": "+1-555-0456",
  "title": "Chief Financial Officer",
  "department": "Finance",
  "status": "ACTIVE",
  "type": "CLIENT_CONTACT",
  "clientId": 789,
  "clientName": "Acme Corporation",
  "isPrimaryContact": true,
  "address": {
    "street": "123 Business Ave",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "communicationPreferences": {
    "preferredMethod": "EMAIL",
    "emailFrequency": "WEEKLY",
    "newsletterSubscription": true,
    "marketingEmails": false
  },
  "notes": "Primary contact for all financial matters and audit communications",
  "createdAt": "2023-01-15T10:00:00Z",
  "updatedAt": "2024-11-20T14:30:00Z"
}

## 🧑‍💼 Staff

Manage staff accounts, roles, and permissions.


### List staff

 - [POST /gql/v1/staff](https://api.doc.aiwyn.ai/bundle/staff/getstaff.md): Staff directory and human resource management with organizational structure

This comprehensive HR endpoint provides complete staff management including:
- Employee directory with advanced search capabilities
- Department and organizational structure integration
- Role-based staff categorization and filtering
- Active/inactive employee status management
- Multi-field name search with partial matching

HR Management Capabilities:
- Complete employee directory with contact information
- Department-based organizational structure tracking
- Staff type and role classification system
- Active employee status for current workforce analysis
- Employee search across first and last names

Organizational Features:
- Department hierarchy and staff allocation
- Role-based access and staff type categorization
- Employee status management (active/inactive)
- Contact information and communication data
- Staff reference and external system integration

Search and Filter Options:
- Multi-field name search (first name, last name)
- Department-based staff filtering
- Active status filtering for current employees
- Role and staff type categorization
- Alphabetical sorting for directory listings

Business Applications:
- Employee directory and contact management
- HR reporting and organizational analysis
- Department staff allocation and planning
- Employee onboarding and management workflows
- Integration with external HR and payroll systems

Directory Features:
- Complete contact information management
- Department and role relationship tracking
- Staff reference system for external integration
- Employee status and lifecycle management

Real Example:
bash
curl --location 'https://{{host}}/v1/staff' \
--data '{
  "pageSize": 25,
  "page": 0
}'


Permissions:

### Search staff

 - [POST /gql/v1/staff/search](https://api.doc.aiwyn.ai/bundle/staff/filterstaffdynamic.md): Advanced staff filtering with custom GraphQL where clauses and dynamic ordering

Provides flexible, enterprise-grade filtering for staff directory queries with boolean logic,
relationship traversal, and multi-field ordering.

Key capabilities include boolean operators (_and, _or, _not), text matching (_ilike),
comparison operators (_gt, _gte, _lt, _lte, _eq, _neq), array operators (_in, _nin),
and nested/related filtering (e.g., by office or manager).

Real Example:
bash
curl --location 'https://{{host}}/v1/staff/search' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "firstName": {
              "_ilike": "%john%"
            }
          },
          {
            "lastName": {
              "_ilike": "%doe%"
            }
          }
        ]
      },
      {
        "active": {
          "_eq": true
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "deptId": {
          "_in": [
            1,
            2,
            3
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "lastName": "asc"
    },
    {
      "firstName": "asc"
    }
  ]
}'

### Get staff member by ID

 - [GET /gql/v1/staff/{id}](https://api.doc.aiwyn.ai/bundle/staff/getstaffbyid.md): Retrieve a specific staff member by their unique identifier

This endpoint provides basic staff member information including:
- Staff member identification and PMS reference
- Personal details (name and email)
- Employment status and organizational structure
- Department and office assignments
- Management hierarchy information

Staff Details Include:
- Staff member ID and PMS reference
- Personal information (first name, last name, email)
- Active status indicator
- Department and office identifiers
- Job title and staff type (when available)
- Manager assignment (when applicable)

Business Applications:
- Staff member lookup and verification
- Organizational structure queries
- Basic staff information retrieval
- Department and office staff management

Real Example:
bash
curl --location 'https://{{host}}/v1/staff/123' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 202,
  "pmsRef": "2254",
  "firstName": "Holley",
  "lastName": "Abbott",
  "email": "ena.toy@hotmail.com",
  "active": true,
  "deptId": 8,
  "jobTitle": null,
  "type": null,
  "officeId": 2,
  "staffManagerId": null
}

## 💳 Payments

Handle incoming and outgoing payments.


### List payments

 - [POST /gql/v1/payments](https://api.doc.aiwyn.ai/bundle/payments/getpayments.md): Retrieve payment records with transaction details and security compliance

This endpoint provides secure payment data access with:
- PCI-compliant payment information (masked card data)
- Payment method categorization and tracking
- Integration with AR transactions for complete context
- Payment processor integration (PayPal, Stripe, etc.)
- Date-based filtering for reconciliation periods
- Client relationship data for payment attribution

Security & Compliance:
- PCI DSS compliant data handling (last 4 digits only)
- Secure payment processor ID tracking
- Payment confirmation date logging
- Audit trail for payment processing

Payment Method Support:
- Credit/debit card payments with masked PAN
- ACH/bank transfer processing
- Check and wire transfer tracking
- Digital wallet integration (PayPal, Apple Pay, etc.)

Reconciliation Features:
- Payment-to-invoice matching via AR transactions
- Payment confirmation status tracking
- Processor reference ID management
- Multi-currency payment support

Business Applications:
- Payment reconciliation and matching
- Revenue recognition and cash flow analysis
- Client payment history and patterns
- Payment method performance analysis
- Compliance reporting and audit trails

Real Example:
bash
curl --location 'https://{{host}}/v1/payments' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search payments

 - [POST /gql/v1/payments/search](https://api.doc.aiwyn.ai/bundle/payments/filterpaymentsdynamic.md): Advanced payment filtering with custom GraphQL where clauses and dynamic ordering

Backed by view vw_payment_history_firm_table. Supports text matching, date ranges, and flags.

Real Example:
bash
curl --location 'https://{{host}}/v1/payments/search' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "paymentMethod": {
              "_ilike": "%CREDIT%"
            }
          },
          {
            "cardType": {
              "_ilike": "%VISA%"
            }
          }
        ]
      },
      {
        "isAutomatic": {
          "_eq": false
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "paymentConfirmationDate": {
          "_is_null": false
        }
      }
    ]
  },
  "orderBy": [
    {
      "paymentConfirmationDate": "desc"
    },
    {
      "createdAt": "desc"
    }
  ]
}'

### Get payment by ID

 - [GET /gql/v1/payment/{id}](https://api.doc.aiwyn.ai/bundle/payments/getpaymentbyid.md): Retrieve a specific payment by its unique identifier

This endpoint provides detailed payment information including:
- Complete payment transaction details
- PCI-compliant payment method information (masked)
- Payment status and confirmation data
- Associated invoice and client relationships
- Payment processor integration details
- Audit trail and security compliance data

Security & Compliance:
- PCI DSS compliant data handling
- Secure payment processor ID tracking
- Payment confirmation date logging
- Audit trail for payment processing

Payment Details Include:
- Payment amount and currency
- Payment method (masked for security)
- Payment status and confirmation
- Associated invoice references
- Client relationship data
- Payment processor details

Business Applications:
- Payment verification and reconciliation
- Client payment history lookup
- Payment dispute resolution
- Audit and compliance reporting
- Payment method analysis

Real Example:
bash
curl --location 'https://{{host}}/v1/payment/12345' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 12345,
  "amount": 1500.00,
  "currency": "USD",
  "paymentMethod": "CREDIT_CARD",
  "cardLastFour": "1234",
  "cardType": "VISA",
  "status": "CONFIRMED",
  "confirmationDate": "2024-01-15T10:30:00Z",
  "processorReference": "stripe_pi_1234567890",
  "clientId": 789,
  "clientName": "Acme Corporation",
  "invoiceId": 456,
  "invoiceNumber": "INV-2024-001",
  "createdAt": "2024-01-15T10:25:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

## 🧾 Billing

Manage billing cycles, statements, and billing configurations.


### List draft invoice histories

 - [POST /gql/v1/draft_invoice_histories](https://api.doc.aiwyn.ai/bundle/billing/getdraftinvoicehistoriespaginated.md): Retrieve draft invoice histories with basic pagination support

Provides paginated access to draft invoice history records.

Real Example:
bash
curl --location 'https://{{host}}/v1/draft_invoice_histories' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search draft invoice histories

 - [POST /gql/v1/draft_invoice_histories/search](https://api.doc.aiwyn.ai/bundle/billing/filterdraftinvoicehistoriesdynamic.md): Advanced draft invoice history filtering with custom GraphQL where clauses and dynamic ordering

Supports client, invoice, job filtering and draftInvoice approvedAt date range.

Real Example:
bash
curl --location 'https://{{host}}/v1/draft_invoice_histories/search' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "clientId": {
              "_in": [1001, 1002]
            }
          },
          {
            "jobId": {
              "_in": [2001, 2002]
            }
          }
        ]
      },
      {
        "active": {
          "_eq": true
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "activityType": {
          "_in": [
            "DRAFT_INVOICE_CREATED",
            "DRAFT_INVOICE_RECONCILED"
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "clientId": "asc"
    },
    {
      "createdAt": "desc"
    }
  ]
}'

### Get draft invoice by ID

 - [GET /gql/v1/draft_invoice/{id}](https://api.doc.aiwyn.ai/bundle/billing/getdraftinvoicebyid.md): Retrieve a specific draft invoice by its unique identifier

This endpoint provides detailed draft invoice information including:
- Complete draft invoice details and line items
- Draft status and review information
- Client and project relationships
- Tax calculations and compliance data
- Review history and approval workflow
- Document generation and delivery preparation

Draft Invoice Management Features:
- Draft invoice lifecycle tracking
- Review and approval workflow
- Tax calculation and compliance
- Client relationship integration
- Document preparation and delivery setup

Draft Invoice Details Include:
- Draft invoice number and reference
- Draft status and review status
- Client and project information
- Line items and amounts
- Tax calculations
- Review history

Business Applications:
- Draft invoice review and approval
- Tax compliance verification
- Client billing preparation
- Revenue recognition planning
- Document generation preparation

Real Example:
bash
curl --location 'https://{{host}}/v1/draft_invoice/56789' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 56789,
  "draftNumber": "DRAFT-2024-001",
  "reference": "Q4-AUDIT-DRAFT-2024",
  "status": "UNDER_REVIEW",
  "reviewStatus": "PENDING_APPROVAL",
  "clientId": 789,
  "clientName": "Acme Corporation",
  "clientEmail": "billing@acme.com",
  "projectId": 67890,
  "projectName": "Q4 Financial Audit",
  "preparedDate": "2024-12-01T00:00:00Z",
  "proposedIssueDate": "2024-12-15T00:00:00Z",
  "proposedDueDate": "2025-01-15T23:59:59Z",
  "subtotal": 20000.00,
  "taxAmount": 2000.00,
  "totalAmount": 22000.00,
  "currency": "USD",
  "lineItems": [
    {
      "id": 1,
      "description": "Financial Statement Audit",
      "quantity": 80,
      "unitPrice": 250.00,
      "amount": 20000.00,
      "taxRate": 0.10,
      "notes": "Includes fieldwork and report preparation"
    }
  ],
  "reviewHistory": [
    {
      "id": 1,
      "reviewerId": 123,
      "reviewerName": "John Smith",
      "reviewDate": "2024-12-05T10:30:00Z",
      "status": "APPROVED",
      "comments": "All calculations verified and approved"
    },
    {
      "id": 2,
      "reviewerId": 124,
      "reviewerName": "Jane Doe",
      "reviewDate": "2024-12-06T14:15:00Z",
      "status": "PENDING_APPROVAL",
      "comments": "Pending final review"
    }
  ],
  "notes": "Draft invoice for Q4 audit services - pending final review",
  "createdAt": "2024-12-01T09:00:00Z",
  "updatedAt": "2024-12-06T14:15:00Z"
}

## 📄 Invoices

Create, send, and manage invoices.


### List invoices

 - [POST /gql/v1/invoices](https://api.doc.aiwyn.ai/bundle/invoices/getinvoices.md): Retrieve invoices with comprehensive filtering and financial data

This endpoint delivers complete invoice management functionality with:
- Advanced pagination for large invoice datasets
- Multi-dimensional filtering (client, status, date ranges)
- Integration with AR transactions for complete financial context
- Tax, interest, and payment status tracking
- Client relationship data for each invoice
- Aggregate counting for reporting and analytics

Key Financial Features:
- Invoice status tracking (PENDING, PAID, OVERDUE, POSTED, etc.)
- Tax and interest calculations included
- Due date monitoring for collections management
- AR transaction linkage for payment reconciliation
- Amount and allocation tracking for financial reporting

Filtering Capabilities:
- Client-specific invoice retrieval
- Status-based filtering for workflow management  
- Date range queries for period reporting
- Sorting by creation date or transaction date

Business Applications:
- Accounts receivable management and aging reports
- Client billing history and statement generation
- Collections management and overdue tracking
- Financial reporting and revenue recognition
- Payment reconciliation and allocation tracking

Real Example:
bash
curl --location 'https://{{host}}/v1/invoices' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search invoices

 - [POST /gql/v1/invoices/search](https://api.doc.aiwyn.ai/bundle/invoices/filterinvoicesdynamic.md): Advanced invoice filtering with custom GraphQL where clauses and dynamic ordering

Supports invoiceNumber text matching, status filtering, and date ranges.

Real Example:
bash
curl --location 'https://{{host}}/v1/invoices/search' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "invoiceNumber": {
              "_ilike": "%2024%"
            }
          },
          {
            "description": {
              "_ilike": "%service%"
            }
          }
        ]
      },
      {
        "status": {
          "_in": ["POSTED", "CLOSED"]
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "dueDate": {
          "_gte": "2024-01-01T00:00:00Z"
        }
      }
    ]
  },
  "orderBy": [
    {
      "invoiceNumber": "asc"
    },
    {
      "createdAt": "desc"
    }
  ]
}'

### Get invoice by ID

 - [GET /gql/v1/invoice/{id}](https://api.doc.aiwyn.ai/bundle/invoices/getinvoicebyid.md): Retrieve a specific invoice by its unique identifier

This endpoint provides detailed invoice information including:
- Complete invoice details and line items
- Invoice status and payment tracking
- Client and project relationships
- Tax calculations and compliance data
- Payment history and outstanding balances
- Document generation and delivery status

Invoice Management Features:
- Invoice lifecycle tracking
- Payment status monitoring
- Tax calculation and compliance
- Client relationship integration
- Document generation and delivery

Invoice Details Include:
- Invoice number and reference
- Invoice status and payment status
- Client and project information
- Line items and amounts
- Tax calculations
- Payment history

Business Applications:
- Invoice status monitoring
- Payment tracking and reconciliation
- Client billing history
- Revenue recognition analysis
- Tax compliance reporting

Real Example:
bash
curl --location 'https://{{host}}/v1/invoice/45678' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 45678,
  "invoiceNumber": "INV-2024-001",
  "reference": "Q4-AUDIT-2024",
  "status": "SENT",
  "paymentStatus": "PARTIALLY_PAID",
  "clientId": 789,
  "clientName": "Acme Corporation",
  "clientEmail": "billing@acme.com",
  "projectId": 67890,
  "projectName": "Q4 Financial Audit",
  "issueDate": "2024-12-01T00:00:00Z",
  "dueDate": "2024-12-31T23:59:59Z",
  "subtotal": 20000.00,
  "taxAmount": 2000.00,
  "totalAmount": 22000.00,
  "currency": "USD",
  "paidAmount": 15000.00,
  "outstandingAmount": 7000.00,
  "lineItems": [
    {
      "id": 1,
      "description": "Financial Statement Audit",
      "quantity": 80,
      "unitPrice": 250.00,
      "amount": 20000.00,
      "taxRate": 0.10
    }
  ],
  "payments": [
    {
      "id": 12345,
      "amount": 15000.00,
      "paymentDate": "2024-12-15T10:30:00Z",
      "paymentMethod": "CREDIT_CARD",
      "status": "CONFIRMED"
    }
  ],
  "notes": "Payment due within 30 days of invoice date",
  "createdAt": "2024-12-01T09:00:00Z",
  "updatedAt": "2024-12-15T10:30:00Z"
}

## 📋 Projects

Handle engagements, projects, and workflow tracking.


### List projects

 - [POST /gql/v1/projects](https://api.doc.aiwyn.ai/bundle/projects/getprojectspaginated.md): Retrieve all projects with basic pagination support

Projects are represented via vw_job. Default ordering by updatedAt desc.

Real Example:
bash
curl --location 'https://{{host}}/v1/projects' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search projects

 - [POST /gql/v1/projects/search](https://api.doc.aiwyn.ai/bundle/projects/filterprojectsdynamic.md): Advanced project filtering with custom GraphQL where clauses and dynamic ordering

Projects are stored in the Jobs table (vw_job view). Supports manager, dates, and flags.

Real Example:
bash
curl --location 'https://{{host}}/v1/projects/search' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "name": {
              "_ilike": "%migration%"
            }
          },
          {
            "serviceDescription": {
              "_ilike": "%review%"
            }
          }
        ]
      },
      {
        "active": {
          "_eq": true
        }
      },
      {
        "updatedAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "partnerId": {
          "_in": [
            101,
            102,
            103
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "updatedAt": "desc"
    },
    {
      "name": "asc"
    }
  ]
}'

### Get project by ID

 - [GET /gql/v1/project/{id}](https://api.doc.aiwyn.ai/bundle/projects/getprojectbyid.md): Retrieve a specific project by its unique identifier

This endpoint provides detailed project information including:
- Complete project details and specifications
- Project status and lifecycle information
- Client and engagement relationships
- Team assignments and resource allocation
- Budget and financial tracking data
- Timeline and milestone information

Project Management Features:
- Project lifecycle tracking
- Resource allocation and team management
- Budget and financial oversight
- Timeline and milestone management
- Client relationship integration

Project Details Include:
- Project name and description
- Project status and phase
- Client and engagement references
- Team member assignments
- Budget and financial data
- Timeline and milestone tracking

Business Applications:
- Project status monitoring
- Resource allocation analysis
- Budget tracking and reporting
- Client project portfolio management
- Team performance analysis

Real Example:
bash
curl --location 'https://{{host}}/v1/project/67890' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 67890,
  "name": "Q4 Financial Audit",
  "description": "Comprehensive financial audit for Q4 2024 including tax preparation and compliance review",
  "status": "IN_PROGRESS",
  "phase": "EXECUTION",
  "clientId": 789,
  "clientName": "Acme Corporation",
  "engagementId": 456,
  "engagementName": "Annual Audit Engagement",
  "startDate": "2024-10-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "budget": 25000.00,
  "currency": "USD",
  "actualCost": 18500.00,
  "teamMembers": [
    {
      "staffId": 123,
      "name": "John Smith",
      "role": "SENIOR_AUDITOR",
      "allocation": 0.8
    },
    {
      "staffId": 124,
      "name": "Jane Doe",
      "role": "AUDITOR",
      "allocation": 0.6
    }
  ],
  "milestones": [
    {
      "id": 1,
      "name": "Planning Phase Complete",
      "dueDate": "2024-10-15T00:00:00Z",
      "status": "COMPLETED"
    },
    {
      "id": 2,
      "name": "Fieldwork Complete",
      "dueDate": "2024-12-15T00:00:00Z",
      "status": "IN_PROGRESS"
    }
  ],
  "createdAt": "2024-09-15T10:00:00Z",
  "updatedAt": "2024-11-20T14:30:00Z"
}

## ⏱ Time

Track and manage billable and non-billable time entries.


### List WIP entries

 - [POST /gql/v1/wip](https://api.doc.aiwyn.ai/bundle/time/getwip.md): Work in Progress tracking with comprehensive financial lifecycle management

This advanced endpoint provides complete WIP management including:
- WIP value tracking from creation through billing completion
- Outstanding balance calculations for unbilled work
- Multi-dimensional analysis (client, job, date-based)
- Financial aggregations for WIP reporting and analysis
- Integration with client and job data for complete context

Financial Tracking Features:
- WIP value recording and outstanding balance calculation
- Billed amount tracking for revenue recognition
- Write-off amount management for uncollectible WIP
- Job and client correlation for project profitability

WIP Lifecycle Management:
- Creation date logging for aging analysis
- WIP type categorization (TIME, EXPENSE, FIXED_FEE, etc.)
- Outstanding value calculation for billing preparation
- Billed amount reconciliation for revenue tracking

Business Intelligence & Reporting:
- Client-specific WIP analysis and aging
- Job-based profitability and WIP tracking
- WIP aging reports for collections management
- Revenue recognition and billing pipeline analysis

Financial Aggregations:
- Total WIP value across filtered records
- Outstanding WIP calculations for billing preparation
- Billed amount summaries for revenue analysis
- Write-off tracking for financial reporting

Advanced Filtering:
- Client-specific WIP retrieval and analysis
- Job-based WIP tracking for project management
- Date range queries for period-specific reporting
- WIP type filtering for category analysis

Real Example:
bash
curl --location 'https://{{host}}/v1/wip' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search WIP entries

 - [POST /gql/v1/wips/search](https://api.doc.aiwyn.ai/bundle/time/filterwipsdynamic.md): Advanced WIP filtering with custom GraphQL where clauses and dynamic ordering

Supports wipType selection, date ranges, and client/job constraints.

Real Example:
bash
curl --location 'https://{{host}}/v1/wips/search' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "type": {
              "_in": ["TIME", "EXPENSE"]
            }
          },
          {
            "notes": {
              "_ilike": "%consultation%"
            }
          }
        ]
      },
      {
        "approved": {
          "_eq": true
        }
      },
      {
        "loggedDate": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "clientId": {
          "_in": [
            1001,
            1002,
            1003
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "loggedDate": "desc"
    },
    {
      "value": "desc"
    }
  ]
}'

### Get WIP time entry by ID

 - [GET /gql/v1/wip/{id}](https://api.doc.aiwyn.ai/bundle/time/getwipbyid.md): Retrieve a specific work-in-progress (WIP) time entry by its unique identifier

This endpoint provides detailed WIP time entry information including:
- Complete time entry details and descriptions
- Time entry status and approval information
- Client, project, and task relationships
- Billable and non-billable time tracking
- Rate calculations and billing preparation
- Time entry history and modifications

WIP Time Management Features:
- Time entry lifecycle tracking
- Billable vs non-billable time classification
- Rate calculation and billing preparation
- Project and task relationship management
- Approval workflow integration

WIP Time Details Include:
- Time entry description and details
- Time entry status and type
- Client, project, and task information
- Time duration and rates
- Billable calculations
- Approval status

Business Applications:
- Time entry review and approval
- Billable time calculation
- Project time tracking
- Client billing preparation
- Productivity analysis

Real Example:
bash
curl --location 'https://{{host}}/v1/wip/89012' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 89012,
  "description": "Financial statement review and analysis",
  "status": "PENDING_APPROVAL",
  "type": "BILLABLE",
  "staffId": 123,
  "staffName": "John Smith",
  "clientId": 789,
  "clientName": "Acme Corporation",
  "projectId": 67890,
  "projectName": "Q4 Financial Audit",
  "taskId": 456,
  "taskName": "Financial Statement Review",
  "date": "2024-11-20T00:00:00Z",
  "startTime": "2024-11-20T09:00:00Z",
  "endTime": "2024-11-20T17:00:00Z",
  "duration": 8.0,
  "billableHours": 8.0,
  "nonBillableHours": 0.0,
  "hourlyRate": 250.00,
  "billableAmount": 2000.00,
  "currency": "USD",
  "notes": "Completed comprehensive review of Q4 financial statements including variance analysis",
  "approvalHistory": [
    {
      "id": 1,
      "approverId": 124,
      "approverName": "Jane Doe",
      "approvalDate": "2024-11-21T10:30:00Z",
      "status": "PENDING",
      "comments": "Under review"
    }
  ],
  "createdAt": "2024-11-20T17:30:00Z",
  "updatedAt": "2024-11-21T10:30:00Z"
}

## ✉️ Engagement

Create, send, and track engagement.


### List engagements

 - [POST /gql/v1/engagements](https://api.doc.aiwyn.ai/bundle/engagement/getengagements.md): Project engagement tracking with comprehensive workflow management

This endpoint delivers complete project engagement management including:
- Client engagement tracking with date-based filtering
- Multi-level staff assignment management (partner and manager roles)
- Project status workflow tracking and reporting
- Template-driven engagement naming and standardization
- Date range analysis for project timeline management

Project Management Capabilities:
- Start and end date tracking for project lifecycles
- Status-based workflow management (ACTIVE, COMPLETED, ON_HOLD, EXECUTED, etc.)
- Staff assignment tracking at partner and manager levels
- Client relationship management for engagement context

Workflow Features:
- Template-based engagement creation for consistency
- Status progression tracking for project milestones
- Staff allocation and responsibility assignment
- Client-specific engagement history and analysis

Business Intelligence:
- Engagement duration analysis and reporting
- Staff utilization and assignment tracking
- Client engagement patterns and history
- Project status distribution and workflow analysis

Filtering and Analysis:
- Client-specific engagement retrieval
- Status-based workflow filtering
- Date range queries for period analysis
- Staff assignment reporting and allocation

Real Example:
bash
curl --location 'https://{{host}}/v1/engagements' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

### Search engagements

 - [POST /gql/v1/engagements/search](https://api.doc.aiwyn.ai/bundle/engagement/searchengagementsdynamic.md): Search Engagements with Dynamic Filters

This endpoint allows you to search engagements using dynamic filters, enabling flexible querying based on various criteria.

Features:
- Supports multiple filter conditions
- Pagination for large result sets
- Sorting options for results

Example Usage:
bash
curl --location 'https://{{host}}/v1/engagements/search' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "name": {
              "_ilike": "%review%"
            }
          },
          {
            "engagementNameTemplate": {
              "_ilike": "%tax%"
            }
          }
        ]
      },
      {
        "status": {
          "_in": ["ACTIVE", "EXECUTED"]
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "partnerStaffId": {
          "_in": [
            5,
            6,
            7,
            8
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "name": "asc"
    },
    {
      "createdAt": "desc"
    }
  ]
}'

### Get engagement by ID

 - [GET /gql/v1/engagement/{id}](https://api.doc.aiwyn.ai/bundle/engagement/getengagementbyid.md): Retrieve a specific engagement by its unique identifier

This endpoint provides detailed engagement information including:
- Complete engagement details and scope
- Engagement status and lifecycle information
- Client relationship and contact details
- Project portfolio and deliverables
- Team assignments and resource allocation
- Financial terms and billing arrangements

Engagement Management Features:
- Engagement lifecycle tracking
- Client relationship management
- Project portfolio oversight
- Team resource allocation
- Financial terms and billing setup

Engagement Details Include:
- Engagement name and description
- Engagement status and type
- Client and contact information
- Project portfolio details
- Team assignments
- Financial terms and billing

Business Applications:
- Engagement status monitoring
- Client relationship management
- Project portfolio analysis
- Resource allocation planning
- Financial performance tracking

Real Example:
bash
curl --location 'https://{{host}}/v1/engagement/34567' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json'


Response Example:
json
{
  "id": 34567,
  "name": "Annual Audit Engagement 2024",
  "description": "Comprehensive annual audit engagement including financial statements, tax preparation, and compliance review",
  "status": "ACTIVE",
  "type": "AUDIT",
  "clientId": 789,
  "clientName": "Acme Corporation",
  "clientEmail": "finance@acme.com",
  "clientPhone": "+1-555-0123",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "estimatedValue": 50000.00,
  "currency": "USD",
  "projects": [
    {
      "id": 67890,
      "name": "Q4 Financial Audit",
      "status": "IN_PROGRESS",
      "budget": 25000.00
    },
    {
      "id": 67891,
      "name": "Tax Preparation",
      "status": "PLANNING",
      "budget": 15000.00
    }
  ],
  "teamMembers": [
    {
      "staffId": 123,
      "name": "John Smith",
      "role": "ENGAGEMENT_PARTNER",
      "allocation": 0.3
    },
    {
      "staffId": 124,
      "name": "Jane Doe",
      "role": "SENIOR_MANAGER",
      "allocation": 0.8
    }
  ],
  "billingTerms": {
    "billingFrequency": "MONTHLY",
    "paymentTerms": "NET_30",
    "rateType": "HOURLY",
    "defaultRate": 250.00
  },
  "notes": "Annual engagement with quarterly reviews and monthly billing",
  "createdAt": "2023-12-15T10:00:00Z",
  "updatedAt": "2024-11-20T14:30:00Z"
}