Skip to main content
GET
https://app.commodityai.com
/
api
/
v1
/
issues
curl -X GET "https://app.commodityai.com/api/v1/issues?status=open&severity=high&limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"
{
  "data": [
    {
      "id": "iss-550e8400-e29b-41d4-a716-446655440000",
      "title": "Contract/Invoice price mismatch",
      "description": "Invoice INV-2024-1847 bills at $14.25/bushel, but the linked contract CON-2024-044 specifies $12.80/bushel. This represents an 11.3% price variance ($1.45/bushel) which exceeds the 5% tolerance threshold. Total financial impact: $72,500 on 50,000 bushels.",
      "severity": "high",
      "status": "open",
      "category": "mismatch",
      "linked_objects": [
        {
          "id": "obj-770e8400-e29b-41d4-a716-446655440001",
          "definition_id": "def-contracts-001",
          "definition_name": "contracts",
          "record_identifier": "CON-2024-044",
          "role": "reference",
          "relevant_fields": {
            "price_per_unit": 12.80,
            "quantity": 50000,
            "counterparty": "Pacific Trading Corp"
          }
        },
        {
          "id": "obj-880e8400-e29b-41d4-a716-446655440002",
          "definition_id": "def-invoices-001",
          "definition_name": "invoices",
          "record_identifier": "INV-2024-1847",
          "role": "compared",
          "relevant_fields": {
            "price_per_unit": 14.25,
            "quantity": 50000,
            "counterparty": "Pacific Trading Corp"
          }
        }
      ],
      "source_documents": [
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440003",
          "filename": "contract-2024-044.pdf",
          "document_type": "contract"
        },
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440004",
          "filename": "invoice-1847.pdf",
          "document_type": "invoice"
        }
      ],
      "discrepancy_details": {
        "field": "price_per_unit",
        "expected_value": 12.80,
        "actual_value": 14.25,
        "variance": 1.45,
        "variance_percent": 11.33
      },
      "assigned_to": null,
      "resolution": null,
      "created_at": "2024-01-22T14:35:00Z",
      "updated_at": "2024-01-22T14:35:00Z"
    },
    {
      "id": "iss-550e8400-e29b-41d4-a716-446655440005",
      "title": "Delivery date mismatch between contract and shipment",
      "description": "Shipment SHP-2024-892 scheduled for March 28, 2024 does not align with contract CON-2024-039 delivery window of April 1-5, 2024. Early delivery may incur storage costs or violate delivery terms.",
      "severity": "medium",
      "status": "open",
      "category": "mismatch",
      "linked_objects": [
        {
          "id": "obj-770e8400-e29b-41d4-a716-446655440006",
          "definition_id": "def-contracts-001",
          "definition_name": "contracts",
          "record_identifier": "CON-2024-039",
          "role": "reference",
          "relevant_fields": {
            "delivery_start": "2024-04-01",
            "delivery_end": "2024-04-05",
            "counterparty": "Midwest Grain Co"
          }
        },
        {
          "id": "obj-880e8400-e29b-41d4-a716-446655440007",
          "definition_id": "def-shipments-001",
          "definition_name": "shipments",
          "record_identifier": "SHP-2024-892",
          "role": "compared",
          "relevant_fields": {
            "scheduled_date": "2024-03-28",
            "counterparty": "Midwest Grain Co"
          }
        }
      ],
      "source_documents": [
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440008",
          "filename": "contract-2024-039.pdf",
          "document_type": "contract"
        },
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440009",
          "filename": "shipping-notice-892.pdf",
          "document_type": "shipment_notice"
        }
      ],
      "discrepancy_details": {
        "field": "delivery_date",
        "expected_value": "2024-04-01 to 2024-04-05",
        "actual_value": "2024-03-28",
        "variance": "-4 days",
        "variance_percent": null
      },
      "assigned_to": "user-110e8400-e29b-41d4-a716-446655440010",
      "resolution": null,
      "created_at": "2024-01-22T15:10:00Z",
      "updated_at": "2024-01-22T15:45:00Z"
    },
    {
      "id": "iss-550e8400-e29b-41d4-a716-446655440011",
      "title": "Quantity variance on invoice",
      "description": "Invoice INV-2024-1901 claims 82,000 bushels delivered, but the associated bill of lading BOL-2024-445 records only 78,500 bushels. Variance of 3,500 bushels (4.3%) exceeds acceptable tolerance.",
      "severity": "high",
      "status": "acknowledged",
      "category": "discrepancy",
      "linked_objects": [
        {
          "id": "obj-770e8400-e29b-41d4-a716-446655440012",
          "definition_id": "def-invoices-001",
          "definition_name": "invoices",
          "record_identifier": "INV-2024-1901",
          "role": "compared",
          "relevant_fields": {
            "quantity": 82000,
            "commodity": "Corn",
            "counterparty": "Delta Commodities LLC"
          }
        },
        {
          "id": "obj-880e8400-e29b-41d4-a716-446655440013",
          "definition_id": "def-bills-of-lading-001",
          "definition_name": "bills_of_lading",
          "record_identifier": "BOL-2024-445",
          "role": "reference",
          "relevant_fields": {
            "quantity": 78500,
            "commodity": "Corn",
            "counterparty": "Delta Commodities LLC"
          }
        }
      ],
      "source_documents": [
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440014",
          "filename": "invoice-1901.pdf",
          "document_type": "invoice"
        },
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440015",
          "filename": "bol-445.pdf",
          "document_type": "bill_of_lading"
        }
      ],
      "discrepancy_details": {
        "field": "quantity",
        "expected_value": 78500,
        "actual_value": 82000,
        "variance": 3500,
        "variance_percent": 4.46
      },
      "assigned_to": "user-110e8400-e29b-41d4-a716-446655440016",
      "resolution": null,
      "created_at": "2024-01-23T09:20:00Z",
      "updated_at": "2024-01-23T10:15:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6ImlzcyI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAxMSJ9",
    "limit": 50,
    "total_count": 127
  }
}
Returns a paginated list of issues (exceptions) identified across your data. Issues represent business-level discrepancies, cross-object validation failures, and data quality problems that require attention—such as misaligned terms between contracts and invoices, quantity variances, or pricing inconsistencies.

Query Parameters

limit
number
default:"100"
Number of issues to return (max: 1000)
cursor
string
Pagination cursor for fetching the next page of results
status
string
Filter by issue status: open, acknowledged, resolved, dismissed
severity
string
Filter by severity level: critical, high, medium, low
category
string
Filter by issue category: mismatch, no_match_found, discrepancy
object_id
string
Filter issues linked to a specific object record
definition_id
string
Filter issues by object definition (e.g., all contract-related issues)

Date Filtering

created_at[operator]
string
Filter by creation timestamp (ISO 8601 format)Supported operators: eq, gt, gte, lt, lteExamples:
  • created_at[gte]=2024-01-01T00:00:00Z - Created on or after Jan 1, 2024
  • created_at[lt]=2024-12-31T23:59:59Z - Created before Dec 31, 2024
updated_at[operator]
string
Filter by last update timestamp (ISO 8601 format)Supported operators: eq, gt, gte, lt, lte

Request Examples

curl -X GET "https://app.commodityai.com/api/v1/issues?status=open&severity=high&limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

Response

{
  "data": [
    {
      "id": "iss-550e8400-e29b-41d4-a716-446655440000",
      "title": "Contract/Invoice price mismatch",
      "description": "Invoice INV-2024-1847 bills at $14.25/bushel, but the linked contract CON-2024-044 specifies $12.80/bushel. This represents an 11.3% price variance ($1.45/bushel) which exceeds the 5% tolerance threshold. Total financial impact: $72,500 on 50,000 bushels.",
      "severity": "high",
      "status": "open",
      "category": "mismatch",
      "linked_objects": [
        {
          "id": "obj-770e8400-e29b-41d4-a716-446655440001",
          "definition_id": "def-contracts-001",
          "definition_name": "contracts",
          "record_identifier": "CON-2024-044",
          "role": "reference",
          "relevant_fields": {
            "price_per_unit": 12.80,
            "quantity": 50000,
            "counterparty": "Pacific Trading Corp"
          }
        },
        {
          "id": "obj-880e8400-e29b-41d4-a716-446655440002",
          "definition_id": "def-invoices-001",
          "definition_name": "invoices",
          "record_identifier": "INV-2024-1847",
          "role": "compared",
          "relevant_fields": {
            "price_per_unit": 14.25,
            "quantity": 50000,
            "counterparty": "Pacific Trading Corp"
          }
        }
      ],
      "source_documents": [
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440003",
          "filename": "contract-2024-044.pdf",
          "document_type": "contract"
        },
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440004",
          "filename": "invoice-1847.pdf",
          "document_type": "invoice"
        }
      ],
      "discrepancy_details": {
        "field": "price_per_unit",
        "expected_value": 12.80,
        "actual_value": 14.25,
        "variance": 1.45,
        "variance_percent": 11.33
      },
      "assigned_to": null,
      "resolution": null,
      "created_at": "2024-01-22T14:35:00Z",
      "updated_at": "2024-01-22T14:35:00Z"
    },
    {
      "id": "iss-550e8400-e29b-41d4-a716-446655440005",
      "title": "Delivery date mismatch between contract and shipment",
      "description": "Shipment SHP-2024-892 scheduled for March 28, 2024 does not align with contract CON-2024-039 delivery window of April 1-5, 2024. Early delivery may incur storage costs or violate delivery terms.",
      "severity": "medium",
      "status": "open",
      "category": "mismatch",
      "linked_objects": [
        {
          "id": "obj-770e8400-e29b-41d4-a716-446655440006",
          "definition_id": "def-contracts-001",
          "definition_name": "contracts",
          "record_identifier": "CON-2024-039",
          "role": "reference",
          "relevant_fields": {
            "delivery_start": "2024-04-01",
            "delivery_end": "2024-04-05",
            "counterparty": "Midwest Grain Co"
          }
        },
        {
          "id": "obj-880e8400-e29b-41d4-a716-446655440007",
          "definition_id": "def-shipments-001",
          "definition_name": "shipments",
          "record_identifier": "SHP-2024-892",
          "role": "compared",
          "relevant_fields": {
            "scheduled_date": "2024-03-28",
            "counterparty": "Midwest Grain Co"
          }
        }
      ],
      "source_documents": [
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440008",
          "filename": "contract-2024-039.pdf",
          "document_type": "contract"
        },
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440009",
          "filename": "shipping-notice-892.pdf",
          "document_type": "shipment_notice"
        }
      ],
      "discrepancy_details": {
        "field": "delivery_date",
        "expected_value": "2024-04-01 to 2024-04-05",
        "actual_value": "2024-03-28",
        "variance": "-4 days",
        "variance_percent": null
      },
      "assigned_to": "user-110e8400-e29b-41d4-a716-446655440010",
      "resolution": null,
      "created_at": "2024-01-22T15:10:00Z",
      "updated_at": "2024-01-22T15:45:00Z"
    },
    {
      "id": "iss-550e8400-e29b-41d4-a716-446655440011",
      "title": "Quantity variance on invoice",
      "description": "Invoice INV-2024-1901 claims 82,000 bushels delivered, but the associated bill of lading BOL-2024-445 records only 78,500 bushels. Variance of 3,500 bushels (4.3%) exceeds acceptable tolerance.",
      "severity": "high",
      "status": "acknowledged",
      "category": "discrepancy",
      "linked_objects": [
        {
          "id": "obj-770e8400-e29b-41d4-a716-446655440012",
          "definition_id": "def-invoices-001",
          "definition_name": "invoices",
          "record_identifier": "INV-2024-1901",
          "role": "compared",
          "relevant_fields": {
            "quantity": 82000,
            "commodity": "Corn",
            "counterparty": "Delta Commodities LLC"
          }
        },
        {
          "id": "obj-880e8400-e29b-41d4-a716-446655440013",
          "definition_id": "def-bills-of-lading-001",
          "definition_name": "bills_of_lading",
          "record_identifier": "BOL-2024-445",
          "role": "reference",
          "relevant_fields": {
            "quantity": 78500,
            "commodity": "Corn",
            "counterparty": "Delta Commodities LLC"
          }
        }
      ],
      "source_documents": [
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440014",
          "filename": "invoice-1901.pdf",
          "document_type": "invoice"
        },
        {
          "id": "src-990e8400-e29b-41d4-a716-446655440015",
          "filename": "bol-445.pdf",
          "document_type": "bill_of_lading"
        }
      ],
      "discrepancy_details": {
        "field": "quantity",
        "expected_value": 78500,
        "actual_value": 82000,
        "variance": 3500,
        "variance_percent": 4.46
      },
      "assigned_to": "user-110e8400-e29b-41d4-a716-446655440016",
      "resolution": null,
      "created_at": "2024-01-23T09:20:00Z",
      "updated_at": "2024-01-23T10:15:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6ImlzcyI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAxMSJ9",
    "limit": 50,
    "total_count": 127
  }
}

Response Fields

data
array
Array of issue objects
meta
object
Pagination and summary metadata

Issue Categories

CategoryDescription
mismatchValues do not match between related objects
no_match_foundExpected related object could not be found
discrepancyData inconsistency or variance detected

Issue Severity

SeverityDescription
criticalSignificant financial exposure or compliance risk; requires immediate attention
highMaterial discrepancy; should be addressed before processing
mediumModerate variance; review recommended
lowMinor discrepancy; informational

Error Codes

StatusCodeDescription
400validation_errorInvalid query parameters
401unauthorizedInvalid or missing API key
429rate_limit_exceededToo many requests (see Rate Limits)
500internal_errorInternal server error