Invoices

The Invoices API lets you upload PDF invoices, track their processing status, view extracted data, and manage invoice lifecycle.

Endpoints

Method	Path	Description
`POST`	`/api/v1/invoices/upload`	Upload an invoice (PDF, max 10MB)
`GET`	`/api/v1/invoices`	List invoices with pagination and filtering
`GET`	`/api/v1/invoices/{id}`	Get invoice detail with extracted data
`DELETE`	`/api/v1/invoices/{id}`	Delete an invoice
`PATCH`	`/api/v1/invoices/{id}/status`	Update invoice status

All endpoints require the X-API-Key header.

Upload Invoice

Upload a PDF file for AI-powered extraction.

curl -X POST https://staging-api.tryenvoyx.com/api/v1/invoices/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Constraints:

File type: PDF only
Max file size: 10MB

Response:

{
  "success": true,
  "status": 201,
  "code": "INVOICE_UPLOADED",
  "message": "Invoice uploaded successfully",
  "data": {
    "id": "clx1234567890",
    "file_name": "invoice.pdf",
    "file_size": 245678,
    "status": "PENDING",
    "uploaded_at": "2024-02-10T12:00:00Z"
  }
}

After upload, the invoice enters the processing pipeline automatically. Use webhooks or WebSockets to get notified when processing completes.

List Invoices

Retrieve a paginated list of invoices with optional status filtering.

curl -X GET "https://staging-api.tryenvoyx.com/api/v1/invoices?page=1&page_size=20&status_filter=PROCESSED" \
  -H "X-API-Key: YOUR_API_KEY"

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`page_size`	integer	`20`	Items per page
`status_filter`	string	—	Filter by status (e.g., `PROCESSED`, `FLAGGED`, `PENDING`)

Response:

{
  "success": true,
  "status": 200,
  "code": "INVOICES_FETCHED",
  "message": "Invoices retrieved successfully",
  "data": {
    "invoices": [
      {
        "id": "clx1234567890",
        "file_name": "invoice.pdf",
        "status": "PROCESSED",
        "uploaded_at": "2024-02-10T12:00:00Z",
        "processed_at": "2024-02-10T12:00:18Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 20
  }
}

Get Invoice Detail

Retrieve a single invoice with full extracted data.

curl -X GET https://staging-api.tryenvoyx.com/api/v1/invoices/{id} \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "status": 200,
  "code": "INVOICE_FETCHED",
  "message": "Invoice retrieved successfully",
  "data": {
    "id": "clx1234567890",
    "file_name": "invoice.pdf",
    "file_size": 245678,
    "file_url": "https://storage.example.com/invoice.pdf?signed=...",
    "status": "PROCESSED",
    "uploaded_at": "2024-02-10T12:00:00Z",
    "processed_at": "2024-02-10T12:00:18Z",
    "extracted_data": {
      "claim_number": "CLM-2024-001",
      "insured_id": "INS-123456",
      "insurance_name": "Blue Cross Blue Shield",
      "patient_name": "John Doe",
      "invoice_number": "INV-2024-0042",
      "submission_date": "2024-02-08",
      "invoice_date": "2024-02-05",
      "insurance_value": 250.00,
      "max_coverage": 500.00,
      "out_of_pocket": 50.00,
      "provider_name": "Dr. Smith Medical Center",
      "service_category": "Medical Consultation",
      "validation_passed": true,
      "validation_flags": []
    }
  }
}

Extracted Data Fields

Field	Type	Description
`claim_number`	string	Insurance claim number
`insured_id`	string	Insured person's ID
`insurance_name`	string	Insurance company name
`patient_name`	string	Patient's full name
`invoice_number`	string	Invoice reference number
`submission_date`	string	Date invoice was submitted
`invoice_date`	string	Date on the invoice
`insurance_value`	number	Amount covered by insurance
`max_coverage`	number	Maximum coverage amount
`out_of_pocket`	number	Patient's out-of-pocket cost
`provider_name`	string	Healthcare provider name
`service_category`	string	Type of medical service
`validation_passed`	boolean	Whether all validation checks passed
`validation_flags`	array	List of validation issues (empty if all passed)

Delete Invoice

Permanently delete an invoice and its extracted data.

curl -X DELETE https://staging-api.tryenvoyx.com/api/v1/invoices/{id} \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "status": 200,
  "code": "INVOICE_DELETED",
  "message": "Invoice deleted successfully"
}

Deletion is permanent. The invoice file and all extracted data will be removed.

Update Invoice Status

Update the status of a processed invoice (e.g., approve, reject, or mark as paid).

curl -X PATCH https://staging-api.tryenvoyx.com/api/v1/invoices/{id}/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "APPROVED"
  }'

Response:

{
  "success": true,
  "status": 200,
  "code": "STATUS_UPDATED",
  "message": "Invoice status updated successfully",
  "data": {
    "id": "clx1234567890",
    "status": "APPROVED",
    "updated_at": "2024-02-11T09:30:00Z"
  }
}

Status Lifecycle

Invoices follow this status progression:

PENDING → PROCESSING → PROCESSED → APPROVED → PAID
                     ↘ FLAGGED  → APPROVED → PAID
                     ↘ FAILED     REJECTED

Status	Description
`PENDING`	Uploaded, awaiting processing
`PROCESSING`	AI extraction in progress
`PROCESSED`	Successfully extracted and validated
`FLAGGED`	Extracted but validation issues detected
`FAILED`	Extraction or processing error
`APPROVED`	Manually approved after review
`REJECTED`	Manually rejected after review
`PAID`	Marked as paid

Valid Status Transitions

Not all transitions are allowed. The API enforces these rules:

From	Allowed To
`PROCESSED`	`APPROVED`, `REJECTED`
`FLAGGED`	`APPROVED`, `REJECTED`
`APPROVED`	`PAID`

System statuses (PENDING, PROCESSING, FAILED) are set automatically and cannot be changed via the API.

Code Examples

Upload and Poll

const apiKey = process.env.ENVOYX_API_KEY

// Upload
const formData = new FormData()
formData.append('file', fs.createReadStream('invoice.pdf'))

const uploadRes = await fetch('https://staging-api.tryenvoyx.com/api/v1/invoices/upload', {
  method: 'POST',
  headers: { 'X-API-Key': apiKey },
  body: formData,
})

const { data: invoice } = await uploadRes.json()
console.log('Uploaded:', invoice.id)

// Poll for completion
let status = 'PENDING'
while (status === 'PENDING' || status === 'PROCESSING') {
  await new Promise(r => setTimeout(r, 3000))

  const res = await fetch(`https://staging-api.tryenvoyx.com/api/v1/invoices/${invoice.id}`, {
    headers: { 'X-API-Key': apiKey },
  })

  const { data } = await res.json()
  status = data.status
  console.log('Status:', status)
}

import requests
import time
import os

api_key = os.getenv('ENVOYX_API_KEY')
headers = {'X-API-Key': api_key}

# Upload
with open('invoice.pdf', 'rb') as f:
    res = requests.post(
        'https://staging-api.tryenvoyx.com/api/v1/invoices/upload',
        headers=headers,
        files={'file': f}
    )

invoice = res.json()['data']
print(f"Uploaded: {invoice['id']}")

# Poll for completion
status = 'PENDING'
while status in ('PENDING', 'PROCESSING'):
    time.sleep(3)
    res = requests.get(
        f"https://staging-api.tryenvoyx.com/api/v1/invoices/{invoice['id']}",
        headers=headers
    )
    status = res.json()['data']['status']
    print(f"Status: {status}")

Next Steps

Set up webhooks to avoid polling
Connect via WebSocket for real-time updates
View dashboard analytics

Invoices

On this page