# 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** - JWT API key exchange for short-lived bearer JWTs
- 📊 **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.

## Testing Enviornments
- **Sandbox** runs the latest development branch.
- **Staging** mirrors production behavior and stability.


Version: 1.0.0

## Servers

Sandbox
```
https://demo.api.aiwyn.ai
```

Staging
```
https://staging.api.aiwyn.app
```

## Security

### BearerAuth

Bearer JWT authentication for Product API access (JWTs are issued via Aiwyn’s `/v1/auth/token` JWT API key exchange).

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

**Token Requirements:**
- JWT tokens are issued by Aiwyn (backed by Firebase), obtained by exchanging a `jwtApiKey` at `/v1/auth/token`
- Tokens contain Hasura role-based permissions and tenant context
- Standard expiration time: 1 hour (3600 seconds)
- 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",
      "aiwynsb_RECORD_R",
      "aiwynsb_RECORD_W",
      "aiwynsb_CUSTOM_TYPE_R",
      "aiwynsb_CUSTOM_TYPE_W"
    ],
    "x-hasura-default-role": "aiwynsb_API_ADMIN"
  },
  "staffId": 420,
  "tenant": "aiwynsb",
  "roles": ["SUPER_ADMIN", "aiwynsb_API_ADMIN", "aiwynsb_RECORD_W", "aiwynsb_CUSTOM_TYPE_W"],
  "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 a JWT API key for a short-lived bearer JWT used to access Product APIs. 

Headers:
- Tenant: your tenant schema (recommended; required by many endpoints)

## 👤 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"
}

### Client Onboarding

 - [POST /api/v1/clients/v1/onboard](https://api.doc.aiwyn.ai/bundle/client/onboardnewclient.md): Onboard a new client with inline contact creation

Creates a new client record and simultaneously resolves or creates up to three
associated contacts (preferred, billing, and secondary). Each contact field accepts
either an existing contact ID or a full inline payload to create a brand-new contact.

Required fields:
- name — client display name
- pmsRef — practice management system reference
- clientRef — unique client reference identifier
- officeId — ID of the office this client belongs to

Contact fields (prefContact, billingContact, secondaryContact):
Each contact field is optional but, when provided, must include either an existing
id or a contactInfo object — not both.
- When supplying contactInfo, pmsRef on the contact payload is required.
- At least one of prefix, firstName, or lastName must be provided inside
  contactInfo to form a valid full name.

Real Example:
bash
curl --location 'https://{{host}}/api/v1/clients/v1/onboard' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Acme Corporation",
  "pmsRef": "ACME-001",
  "clientRef": "ACME-001",
  "officeId": 1,
  "prefContact": {
    "pmsRef": "CONT-001",
    "contactInfo": {
      "pmsRef": "CONT-001",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@acme.com"
    }
  }
}'

## 👥 Client Group

Manage client group records and associated staff assignments.


### List client groups

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

This endpoint returns a paginated list of all client groups in the tenant,
including assigned partner/manager staff and office information.

Key Features:
- Basic pagination with configurable page sizes (default: 50 records)
- Default sorting by client group name (ascending) then creation date (descending)
- Total count aggregation for pagination metadata

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

## 📇 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"
}

### Get contacts by client ID

 - [GET /gql/v1/contacts/by_client/{clientId}](https://api.doc.aiwyn.ai/bundle/contact/getcontactsbyclientid.md): Retrieve active contacts associated with a specific client

Returns all contacts linked to the given client via the contact-client relationship,
where the contact, contact-client link, and contact info are all active.

Results are ordered by last name then first name.

Real Example:
bash
curl --location 'https://{{host}}/v1/contacts/by_client/789' \
--header 'Authorization: bearer {{token}}'

## 🧩 Client Business Entity

Manage client business entities used for client categorization and structure.


### List client business entities

 - [POST /gql/v1/client_business_entities](https://api.doc.aiwyn.ai/bundle/client-business-entity/getclientbusinessentitiespaginated.md): Retrieve all client business entities with basic pagination support

This is a read-only lookup endpoint backed by Hasura. It is useful after creating records via /api/v1/records.

## 🔗 Contact Client

Manage contact ↔ client relationship records.


### List contact-client relationships

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

This is a read-only lookup endpoint backed by Hasura.

## 🪪 Contact Info

Manage contact information records (address, email, phone, etc.).


### List contact infos

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

This is a read-only lookup endpoint backed by Hasura.

## 🏢 Department

Manage departments and organizational units.


### List departments

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

This is a read-only lookup endpoint backed by Hasura.

## 🏭 Industry

Manage industry classifications.


### List industries

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

This is a read-only lookup endpoint backed by Hasura.

## 🧾 Job

Manage jobs/projects.


### List jobs

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

This is a read-only lookup endpoint backed by Hasura.

### Get job by ID

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

This is a read-only lookup endpoint backed by Hasura.

## 🧩 Job Template

Manage job templates.


### List job templates

 - [POST /gql/v1/job_templates](https://api.doc.aiwyn.ai/bundle/job-template/getjobtemplatespaginated.md): Retrieve all job templates with basic pagination support

This is a read-only lookup endpoint backed by Hasura.

## 🏬 Office

Manage office locations.


### List offices

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

This is a read-only lookup endpoint backed by Hasura.

## 🏛 Org

Manage organizations.


### List orgs

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

This is a read-only lookup endpoint backed by Hasura.

## 🧷 Service Line

Manage service line classifications.


### List service lines

 - [POST /gql/v1/service_lines](https://api.doc.aiwyn.ai/bundle/service-line/getservicelinespaginated.md): Retrieve all service lines with basic pagination support

This is a read-only lookup endpoint backed by Hasura.

## 🧑‍💼 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
}

### Create staff types in batch

 - [POST /api/v1/staff/type/batch/create](https://api.doc.aiwyn.ai/bundle/staff/stafftypebatchcreate.md): Create staff types in batch

            Creates up to 100 staff types in a single request.

            Notes:
            - The request body is JSON `{ "items": [ ... ] } where items is an array of staff type objects (same shape as single /create).
            - items must contain 1–100 elements; otherwise the request is rejected with 400.
            - Successful creates appear under succeeded; failures appear under failed` with an error message (partial success is allowed).
            - 201 when every item succeeds; 422 when every item fails; 200 when there is a mix of successes and failures.

Real Example:
bash
curl --location 'https://{{host}}/api/v1/staff/type/batch/create' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "items": example value
}'

### Lookup staff types (paged)

 - [POST /api/v1/staff/type/batch/lookup](https://api.doc.aiwyn.ai/bundle/staff/stafftypebatchlookup.md): Lookup staff types page by page

            Returns a page of staff types ordered by id ascending.

            Notes:
            - pageSize must be between 1 and 100
            - page is zero-based (page 0 is the first page)

Real Example:
bash
curl --location 'https://{{host}}/api/v1/staff/type/batch/lookup' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "page": 1
}'

## 💳 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 Management

Track and manage billable and non-billable time entries.


### List all task types

 - [GET /v1/task-types](https://api.doc.aiwyn.ai/bundle/time-management/gettasktypes.md): Retrieve all task types

Returns every task type available for the tenant, ordered alphabetically by
display name. Task types classify the work performed on time entries and
projects, and carry billing and tax settings used downstream in invoicing.

Each task type includes:
- Display name, code, and description
- Billing and tax flags (billable, taxable)
- Optional custom hourly rate and rate type
- Service line and category associations
- Usage counts across projects and invoices
- Aiwyn-managed vs firm-defined indicators
- Active status and audit timestamps

Real Example:
bash
curl --location 'https://{{host}}/v1/task-types' \
--header 'Authorization: Bearer {{token}}'

### Search task types

 - [POST /v1/task-types/search](https://api.doc.aiwyn.ai/bundle/time-management/searchtasktypesdynamic.md): Advanced task type filtering with custom GraphQL where clauses and dynamic ordering

Supports flexible filtering across any task type field using GraphQL-style where
clauses, with pagination and dynamic ordering.

Common filter examples (pass in the where field):
- By code:          { "code": { "_eq": "PREP" } }
- By active status: { "active": { "_eq": true } }
- By billable flag: { "billable": { "_eq": true } }
- By category:      { "taskTypeCategoryId": { "_eq": 5 } }
- By service line:  { "serviceLineId": { "_eq": 2 } }
- Combined:         { "_and": [ { "billable": { "_eq": true } }, { "active": { "_eq": true } } ] }

Real Example:
bash
curl --location 'https://{{host}}/v1/task-types/search' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0,
  "where": {
    "_and": [
      { "billable": { "_eq": true } },
      { "active": { "_eq": true } }
    ]
  },
  "orderBy": [
    { "display": "asc" }
  ]
}'

### Get task by ID

 - [GET /v1/task/{id}](https://api.doc.aiwyn.ai/bundle/time-management/findtaskbyid.md): Retrieve a specific task by its unique identifier

Returns full task details including the associated task type, assignee staff
member, and parent job reference.

Real Example:
bash
curl --location 'https://{{host}}/v1/task/456' \
--header 'Authorization: Bearer {{token}}'

### Search tasks

 - [POST /v1/tasks/search](https://api.doc.aiwyn.ai/bundle/time-management/searchtasksdynamic.md): Advanced task filtering with custom GraphQL where clauses and dynamic ordering

Supports flexible filtering across any task field — including nested relations
such as taskType and job — using GraphQL-style where clauses, with
pagination and dynamic ordering.

Common filter examples (pass in the where field):
- By task type ID:   { "taskTypeId": { "_eq": 123 } }
- By task type code: { "taskType": { "code": { "_eq": "PREP" } } }
- By client:         { "job": { "clientId": { "_eq": 456 } } }
- Start date range:  { "startDate": { "_gte": "2024-01-01", "_lte": "2024-12-31" } }
- Due date range:    { "dueDate": { "_gte": "2024-01-01", "_lte": "2024-12-31" } }
- By assignee:       { "assigneeStaffId": { "_eq": 789 } }
- Combined:          { "_and": [ { "taskType": { "code": { "_eq": "PREP" } } }, { "assigneeStaffId": { "_eq": 789 } } ] }

Real Example:
bash
curl --location 'https://{{host}}/v1/tasks/search' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0,
  "where": {
    "_and": [
      { "taskType": { "code": { "_eq": "PREP" } } },
      { "assigneeStaffId": { "_eq": 789 } }
    ]
  },
  "orderBy": [
    { "dueDate": "asc" }
  ]
}'

### List WIP entries

 - [POST /gql/v1/wip](https://api.doc.aiwyn.ai/bundle/time-management/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-management/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-management/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"
}

### List available time management code record types

 - [GET /api/v1/codes/types](https://api.doc.aiwyn.ai/bundle/time-management/listtimemanagementcodetypes.md): List available time management code record types

            Returns the code types that can be managed via the Product API under /api/v1/codes.

### Get field schema for a time management code type

 - [GET /api/v1/codes/schema/{type}](https://api.doc.aiwyn.ai/bundle/time-management/gettimemanagementcodeschema.md): Get field schema for a time management code type

            Returns field definitions for the requested code type.

### Create or update time management code records (upsert)

 - [POST /api/v1/codes](https://api.doc.aiwyn.ai/bundle/time-management/upserttimemanagementcodes.md): Create or update time management code records (upsert)

            Records are created if they don't exist, or updated if matched by systemRef.
            Maximum 100 records per request.

Real Example:
bash
curl --location 'https://{{host}}/api/v1/codes' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "records": example value
}'

### Lookup time management code records in pages (by type)

 - [POST /api/v1/codes/batch/{type}](https://api.doc.aiwyn.ai/bundle/time-management/pagedlookuptimemanagementcodes.md): Lookup time management code records in pages

            Request body:
            { "pageSize": 25, "page": 0 }

Real Example:
bash
curl --location 'https://{{host}}/api/v1/codes/batch/{type}' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "page": 1
}'

### List available time management entry record types

 - [GET /api/v1/entries/types](https://api.doc.aiwyn.ai/bundle/time-management/listtimemanagemententrytypes.md): List available time management entry record types

            Returns the entry types that can be managed via the Product API under /api/v1/entries.

### Get field schema for a time management entry type

 - [GET /api/v1/entries/schema/{type}](https://api.doc.aiwyn.ai/bundle/time-management/gettimemanagemententryschema.md): Get field schema for a time management entry type

            Returns field definitions for the requested entry type.

### Create or update time management entry records (upsert)

 - [POST /api/v1/entries](https://api.doc.aiwyn.ai/bundle/time-management/upserttimemanagemententries.md): Create or update time management entry records (upsert)

            Records are created if they don't exist, or updated if matched by systemRef.
            Maximum 100 records per request.

Real Example:
bash
curl --location 'https://{{host}}/api/v1/entries' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "records": example value
}'

### Lookup time management entry records in pages (by type)

 - [POST /api/v1/entries/batch/{type}](https://api.doc.aiwyn.ai/bundle/time-management/pagedlookuptimemanagemententries.md): Lookup time management entry records in pages

            Request body:
            { "pageSize": 25, "page": 0 }

Real Example:
bash
curl --location 'https://{{host}}/api/v1/entries/batch/{type}' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "page": 1
}'

## ✉️ 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"
}

### Update an existing engagement

 - [PATCH /api/v1/engagements/{engagementId}](https://api.doc.aiwyn.ai/bundle/engagement/updateengagement.md): Update an existing engagement by ID

Partially updates an engagement. Only the fields included in the request body
are modified — omitted fields are left unchanged. At least one field must be
provided.

Updatable Fields:
- Core engagement data (client, fiscal year, partner/manager staff, contacts,
  start/end dates, billing contact, CC staff, name template)
- Engagement letter template and document template
- Additional clients assigned to the engagement (full replace when provided)
- Linked jobs/projects (full replace when provided)

Validation:
- The engagement must exist (404 if not found)
- The engagement must be in DRAFT or UNDER_REVISION status (400 otherwise)
- All provided IDs (additional client IDs, job IDs, etc.) must reference valid records
- At least one field must be provided (400 if request body is empty)

Replace behavior: When additionalClientIds or jobIds is provided, it fully replaces
the existing associations — it is not additive. When jobIds is provided without
additionalClientIds, the existing additional clients are preserved.

Note: Nullable fields (e.g. secondaryContactId, endDate) cannot be
explicitly cleared to null via this endpoint — omitting them leaves the
existing value unchanged.

Real Example:
bash
curl --location --request PATCH 'https://{{host}}/api/v1/engagements/12345' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "fiscalYear": 2025,
  "partnerStaffId": 456,
  "additionalClientIds": [789, 790]
}'


Response Example:
json
{
  "id": 12345
}

### Create a single engagement

 - [POST /api/v1/engagements/create](https://api.doc.aiwyn.ai/bundle/engagement/createengagementletter.md): Create a single engagement letter

Creates an engagement letter for a specific client. The engagement letter
will be associated with the specified client, fiscal year, and assigned staff.

Required fields:
- clientId — the client for whom the engagement is being created
- fiscalYear — the fiscal year of the engagement
- partnerStaffId — the partner staff member assigned to the engagement
- managerStaffId — the manager staff member assigned to the engagement
- primaryContactId — the primary client contact

Optional fields:
- engagementLetterTemplateId / documentTemplateId — which template to use
- engagementNameTemplate — override the firm's default naming template
- startDate / endDate — engagement date range
- billingContactId — contact responsible for billing
- secondaryContactId — secondary client contact
- ccStaffIds — additional staff members to CC on the engagement
- additionalClientIds — additional clients to associate with the engagement
- jobIds — jobs/projects to link to the engagement

Real Example:
bash
curl --location 'https://{{host}}/api/v1/engagements/create' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "clientId": 420,
  "fiscalYear": 2024,
  "partnerStaffId": 53,
  "managerStaffId": 15,
  "primaryContactId": 101
}'

### Create a batch of engagements

 - [POST /api/v1/engagements/batch/create](https://api.doc.aiwyn.ai/bundle/engagement/createbatchengagementletters.md): Create a batch of engagement letters asynchronously

Submits a batch of engagement letter creation requests. The batch is processed
asynchronously — use the returned batch ID with the
GET /api/v1/engagements/batch/{batchId}/status endpoint to poll for completion
and retrieve the IDs of the created engagements.

Batch-level options:
- name — optional label for the batch
- projectTemplateId — apply a single project template to every engagement in the batch
- includeAdditionalClients — include additional clients when creating engagements
- batchEngagements — array of individual engagement records (required)

Constraint: You may provide either projectTemplateId (top-level) or projectIds
on individual engagements — not both.

Real Example:
bash
curl --location 'https://{{host}}/api/v1/engagements/batch/create' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "2024 Annual Batch",
  "batchEngagements": [
    {
      "clientId": 420,
      "fiscalYear": 2024,
      "partnerStaffId": 53,
      "managerStaffId": 15,
      "primaryContactId": 101
    },
    {
      "clientId": 421,
      "fiscalYear": 2024,
      "partnerStaffId": 53,
      "managerStaffId": 15,
      "primaryContactId": 201
    }
  ]
}'

### Get engagement batch status

 - [GET /api/v1/engagements/batch/{batchId}/status](https://api.doc.aiwyn.ai/bundle/engagement/getengagementbatchstatus.md): Retrieve the status of an engagement batch

Returns the current processing status of a previously submitted engagement batch,
along with the IDs of any engagements that have been created so far.

Use this endpoint to poll for completion after calling
POST /api/v1/engagements/batch/create.

Batch statuses:
- DRAFT — batch has been recorded but processing has not started
- CREATING — engagements are actively being created
- CREATED — all engagements in the batch have been created successfully
- CANCELED — the batch was canceled before completion

Real Example:
bash
curl --location 'https://{{host}}/api/v1/engagements/batch/9001/status' \
--header 'Authorization: Bearer {{token}}'

### Get engagement documents by engagement ID

 - [GET /gql/v1/engagement_documents/by_engagement/{engagementId}](https://api.doc.aiwyn.ai/bundle/engagement/getengagementdocumentsbyengagementid.md): Retrieve documents associated with a specific engagement

Returns all engagement documents linked to the given engagement ID, including
the document type name for each record.

Real Example:
bash
curl --location 'https://{{host}}/v1/engagement_documents/by_engagement/34567' \
--header 'Authorization: bearer {{token}}'

## 🗃️ Records

Create, update, and manage entity records across standard and custom record types.

The Records API provides:
- **Record Operations** - Create, update, and delete records for any entity type
- **Schema Discovery** - Query available entity types and their field definitions
- **Custom Record Types** - Define and manage custom record type schemas


### Create or update records (upsert)

 - [POST /api/v1/records](https://api.doc.aiwyn.ai/bundle/records/createorupdaterecords.md): Create or update records (upsert)

            Records are created if they don't exist, or updated if matched by systemRef.

            Partial Success Behavior:
            - Each record is processed independently
            - Successful records are persisted even if others fail
            - Check summary.failed and individual records[].status for failures
            - Failed records include error details in records[].error

            Limits: Maximum 100 records per request.

Business Applications:
- Bulk record import
- Entity synchronization

Real Example:
bash
curl --location 'https://{{host}}/api/v1/records' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "records": example value
}'

### Update records (fails if not found)

 - [PUT /api/v1/records](https://api.doc.aiwyn.ai/bundle/records/updaterecords.md): Update existing records only

            Only updates existing records. Returns error if record not found by systemRef.
            The systemRef field is required for all records in PUT requests.

            Partial Success Behavior:
            - Each record is processed independently
            - Successful records are persisted even if others fail
            - Records not found will have status FAILED with error code RECORD_NOT_FOUND
            - Check summary.failed and individual records[].status for failures

            Limits: Maximum 100 records per request.

Business Applications:
- Strict update workflows
- Guaranteed existence updates

Real Example:
bash
curl --location 'https://{{host}}/api/v1/records' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "records": example value
}'

### Delete (inactivate) records

 - [DELETE /api/v1/records](https://api.doc.aiwyn.ai/bundle/records/deleterecords.md): Delete (inactivate) records

            Soft-deletes records by marking them as inactive. Returns error if record not found.
            The systemRef field is required for all records in DELETE requests.

            Partial Success Behavior:
            - Each record is processed independently
            - Successful deletions are persisted even if others fail
            - Records not found will have status FAILED with error code RECORD_NOT_FOUND
            - Check summary.failed and individual records[].status for failures

            Limits: Maximum 100 records per request.

Business Applications:
- Bulk inactivation
- Record cleanup

### List available record types

 - [GET /api/v1/records/types](https://api.doc.aiwyn.ai/bundle/records/listentitytypes.md): List available record types

            Returns record types that can be managed via this API, with schema URLs.

Business Applications:
- Discover record types

### Get field schema for a record type

 - [GET /api/v1/records/schema/{type}](https://api.doc.aiwyn.ai/bundle/records/getentityschema.md): Get field schema for a record type

            Returns field definitions including types, validation, and foreign key relationships.

Business Applications:
- Dynamic form generation
- Field validation
- Integration mapping

### List all custom record types

 - [GET /api/v1/records/custom](https://api.doc.aiwyn.ai/bundle/records/listcustomrecordtypes.md): List all custom record types

            Returns all custom record type definitions for the tenant.
            Use includeInactive=true to include deactivated record types.

Business Applications:
- Discover custom record types
- Integration configuration

### Create a new custom record type

 - [POST /api/v1/records/custom](https://api.doc.aiwyn.ai/bundle/records/createcustomrecordtype.md): Create a new custom record type

            Creates a new custom record type with the specified field schema.
            The record type name must be unique and follow naming conventions.

Business Applications:
- Define custom data structures
- Extend system capabilities

Real Example:
bash
curl --location 'https://{{host}}/api/v1/records/custom' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Example Name",
  "displayName": "Example Name",
  "description": "example value"
}'

### Get a custom record type by name

 - [GET /api/v1/records/custom/{name}](https://api.doc.aiwyn.ai/bundle/records/getcustomrecordtype.md): Get a custom record type by name

            Returns the full definition of a custom record type including its field schema.

Business Applications:
- View record type schema
- Integration setup

### Update a custom record type

 - [PUT /api/v1/records/custom/{name}](https://api.doc.aiwyn.ai/bundle/records/updatecustomrecordtype.md): Update a custom record type

            Updates an existing custom record type. Only provided fields will be updated.
            Note: Changing fields may affect existing data.

Business Applications:
- Modify record type definitions
- Add new fields

Real Example:
bash
curl --location 'https://{{host}}/api/v1/records/custom/{name}' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "displayName": "Example Name",
  "description": "example value",
  "fields": example value
}'

### Deactivate a custom record type

 - [DELETE /api/v1/records/custom/{name}](https://api.doc.aiwyn.ai/bundle/records/deactivatecustomrecordtype.md): Deactivate a custom record type

            Soft-deletes a custom record type by marking it as inactive.
            Existing data is preserved but the type will no longer appear in lists.

Business Applications:
- Remove custom record types
- Clean up unused definitions

## 🔔 Event Subscriptions

Create and manage webhook subscriptions for entity events.

The Event Subscriptions API provides:
- **Webhook Management** - Create, update, and deactivate webhook subscriptions
- **Event Filtering** - Subscribe to specific entity types and operations (CREATE, UPDATE, DELETE)
- **Security** - Retrieve webhook signing secrets for payload verification


### Get available event types catalog

 - [GET /api/v1/event-subscriptions/catalog](https://api.doc.aiwyn.ai/bundle/event-subscriptions/geteventsettingscatalog.md): Get catalog of available event types

            Returns all entity/operation combinations that can be subscribed to.
            Use the 'enabled' query parameter to filter by enabled status.

Business Applications:
- Discover available events
- Integration planning

### Create a webhook subscription

 - [POST /api/v1/event-subscriptions](https://api.doc.aiwyn.ai/bundle/event-subscriptions/createeventsubscription.md): Create a webhook subscription for entity events

            Subscribe to receive webhook notifications when entities are created, updated, or deleted.
            The webhook URL must use HTTPS and will receive POST requests with event data.

Business Applications:
- Real-time integrations
- Event-driven workflows
- System synchronization

Real Example:
bash
curl --location 'https://{{host}}/api/v1/event-subscriptions' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "entityType": example value,
  "operation": example value,
  "deliveryUrl": "example value"
}'

### Update a webhook subscription

 - [PATCH /api/v1/event-subscriptions/{id}](https://api.doc.aiwyn.ai/bundle/event-subscriptions/updateeventsubscription.md): Update an existing webhook subscription

            Modify subscription properties such as delivery URL, filter expression, or description.
            Only provided fields will be updated.

Business Applications:
- Update webhook URLs
- Modify event filters

### Deactivate a webhook subscription

 - [DELETE /api/v1/event-subscriptions/{id}](https://api.doc.aiwyn.ai/bundle/event-subscriptions/deactivateeventsubscription.md): Deactivate a webhook subscription

            Soft-deletes a subscription by marking it as inactive.
            The subscription can be reactivated later if needed.

Business Applications:
- Stop receiving webhooks
- Cleanup unused subscriptions

### Reactivate a webhook subscription

 - [POST /api/v1/event-subscriptions/{id}/reactivate](https://api.doc.aiwyn.ai/bundle/event-subscriptions/reactivateeventsubscription.md): Reactivate a webhook subscription

            Reactivates a previously deactivated subscription.

Business Applications:
- Restore webhook integrations
- Resume event notifications

Real Example:
bash
curl --location 'https://{{host}}/api/v1/event-subscriptions/{id}/reactivate' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \

### Retrieve webhook delivery attempts for a subscription

 - [GET /api/v1/event-subscriptions/{id}/deliveries](https://api.doc.aiwyn.ai/bundle/event-subscriptions/getwebhookdeliveryhistory.md): Retrieve webhook delivery attempts for a subscription

            Returns a paginated list of delivery attempts for webhook events for the given subscription.
            Supports filtering by HTTP status code and time range.

Business Applications:
- Webhook troubleshooting
- Delivery monitoring
- Operational auditing

### Get webhook signing secret

 - [GET /api/v1/event-subscriptions/webhook/secret](https://api.doc.aiwyn.ai/bundle/event-subscriptions/getsubscriptionsecret.md): Get the webhook signing secret

            Retrieves the secret used to sign webhook payloads.
            Use this secret to verify webhook authenticity on your server.

Business Applications:
- Webhook signature verification
- Security setup

### Generate a test webhook payload and signature

 - [POST /api/v1/webhook/test/generate](https://api.doc.aiwyn.ai/bundle/event-subscriptions/generatewebhooktestpayload.md): Generate a signed test webhook payload

            Generates a signature for an arbitrary JSON payload using the provided secret.
            This is intended for debugging webhook integrations.

Business Applications:
- Webhook troubleshooting
- Signature validation testing

Real Example:
bash
curl --location 'https://{{host}}/api/v1/webhook/test/generate' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \

### Validate a webhook signature

 - [POST /api/v1/webhook/test/validate](https://api.doc.aiwyn.ai/bundle/event-subscriptions/validatewebhooktestsignature.md): Validate a webhook signature

            Verifies that the provided signature matches the payload and secret.
            This is intended for debugging webhook integrations.

Business Applications:
- Webhook troubleshooting
- Signature validation testing

Real Example:
bash
curl --location 'https://{{host}}/api/v1/webhook/test/validate' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \

## 📁 File

Download and access files associated with records and documents.


### Get file metadata by ID

 - [GET /api/v1/files/{id}](https://api.doc.aiwyn.ai/bundle/file/getfilebyid.md): Retrieve file metadata by Aiwyn ID

            Returns file metadata including filename, source type, status, and optional download URL.

            Query Parameters:
            - includeDownloadUrl (optional, default: false) - When true, generates a time-limited signed download URL

            Response includes:
            - File metadata (id, filename, fileSource, fileStatus, active, timestamps)
            - FileInfo metadata (size, creator information) if available
            - Signed download URL (only when includeDownloadUrl=true and file has GCS path)

            Note: Download URLs are time-limited (15 minutes) and should be used promptly.

Business Applications:
- Retrieve file metadata for display
- Generate download URLs for file access
- Verify file existence and status