Skip to content
/
List invoices

Aiwyn API (1.0.0)

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.

Download OpenAPI description
bundle.json
bundle.yaml
Overview
URL
https://www.aiwyn.ai/
Aiwyn API Support
api-support@aiwyn.com
Languages
Servers
Mock server
https://api.doc.aiwyn.ai/_mock/bundle/
Staging Environment (Test Data)
https://demo.api.aiwyn.ai/

🔐 Authentication

Authentication endpoints for obtaining access tokens and managing API keys.

Operations

👤 Client

Manage client records, profiles, and related operations.

Operations

📇 Contact

Manage contact information and relationships for clients.

Operations

🧑‍💼 Staff

Manage staff accounts, roles, and permissions.

Operations

💳 Payments

Handle incoming and outgoing payments.

Operations

🧾 Billing

Manage billing cycles, statements, and billing configurations.

Operations

📄 Invoices

Create, send, and manage invoices.

Operations

List invoices

Request

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:

curl --location 'https://{{host}}/v1/invoices' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'
Security
BearerAuth
Bodyapplication/json
pageSizeinteger[ 1 .. 1000 ]

Maximum number of invoice records to return

Default 25
Example: 25
pageinteger>= 0

Page number for pagination (0-based)

Default 0
Example: 0
clientIdinteger

Filter invoices by specific client ID

Example: 7720
statusstring

Filter by invoice status

Enum"PENDING""POSTED""PAID""OVERDUE""CANCELLED""DRAFT"
Example: "POSTED"
startDatestring(date-time)

Start date for invoice date range filter

Example: "1990-01-01T00:00:00"
endDatestring(date-time)

End date for invoice date range filter

Example: "2024-12-31T23:59:59"
sortOrderstring

Sort order for invoice dates

Default "desc"
Enum"asc""desc"
Example: "desc"
curl -i -X POST \
  https://api.doc.aiwyn.ai/_mock/bundle/gql/v1/invoices \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "pageSize": 25,
    "page": 0
  }'

Responses

Successfully retrieved invoice records

Bodyapplication/json
deid_invoiceArray of objects
deid_invoice_aggregateobject
Response
application/json
{
  "deid_invoice": [
    { … },
    { … },
    { … }
  ],
  "deid_invoice_aggregate": {
    "aggregate": { … }
  }
}

Search invoices

Request

Advanced invoice filtering with custom GraphQL where clauses and dynamic ordering

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

Real Example:

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"
    }
  ]
}'
Security
BearerAuth
Bodyapplication/json
pageSizeinteger[ 1 .. 1000 ]
Default 1
whereobject

GraphQL-style where clause for complex invoice filtering

Example: {"_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"}}]}
orderByArray of objects

Dynamic ordering specifications

Example: [{"invoiceNumber":"asc"},{"createdAt":"desc"}]
curl -i -X POST \
  https://api.doc.aiwyn.ai/_mock/bundle/gql/v1/invoices/search \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
      }
    ]
  }'

Responses

Successfully retrieved filtered invoices

Get invoice by ID

Request

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:

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

Response Example:

{
  "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"
}
Security
BearerAuth
Path
idinteger>= 1required

Unique identifier of the invoice

Example: 45678
curl -i -X GET \
  https://api.doc.aiwyn.ai/_mock/bundle/gql/v1/invoice/45678 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Invoice details retrieved successfully

Bodyapplication/json
idinteger

Unique invoice identifier

Example: 45678
invoiceNumberstring

Invoice number

Example: "INV-2024-001"
referencestring

Invoice reference or description

Example: "Q4-AUDIT-2024"
statusstring

Invoice status

Enum"DRAFT""SENT""VIEWED""PAID""OVERDUE""CANCELLED"
Example: "SENT"
paymentStatusstring

Payment status

Enum"UNPAID""PARTIALLY_PAID""PAID""OVERDUE"
Example: "PARTIALLY_PAID"
clientIdinteger

Associated client identifier

Example: 789
clientNamestring

Client name

Example: "Acme Corporation"
clientEmailstring

Client billing email

Example: "billing@acme.com"
projectIdinteger

Associated project identifier

Example: 67890
projectNamestring

Project name

Example: "Q4 Financial Audit"
issueDatestring(date-time)

Invoice issue date

Example: "2024-12-01T00:00:00Z"
dueDatestring(date-time)

Invoice due date

Example: "2024-12-31T23:59:59Z"
subtotalnumber(decimal)

Invoice subtotal before tax

Example: 20000
taxAmountnumber(decimal)

Total tax amount

Example: 2000
totalAmountnumber(decimal)

Total invoice amount including tax

Example: 22000
currencystring

Invoice currency code

Example: "USD"
paidAmountnumber(decimal)

Total amount paid to date

Example: 15000
outstandingAmountnumber(decimal)

Outstanding balance

Example: 7000
lineItemsArray of objects

Invoice line items

paymentsArray of objects

Payment history for this invoice

notesstring

Additional notes or terms

Example: "Payment due within 30 days of invoice date"
createdAtstring(date-time)

Invoice creation timestamp

Example: "2024-12-01T09:00:00Z"
updatedAtstring(date-time)

Last update timestamp

Example: "2024-12-15T10:30:00Z"
Response
application/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,
  "taxAmount": 2000,
  "totalAmount": 22000,
  "currency": "USD",
  "paidAmount": 15000,
  "outstandingAmount": 7000,
  "lineItems": [
    { … }
  ],
  "payments": [
    { … }
  ],
  "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.

Operations

⏱ Time

Track and manage billable and non-billable time entries.

Operations

✉️ Engagement

Create, send, and track engagement.

Operations

🛤 Last Mile

Handle the final delivery stage and client closing processes.