# Contractor Payment Application Audit API

> Check contractor payment applications against schedule of values, measured work, approved variations, previous certificates, retention rules, and deductions. Every adjustment includes calculation evidence and a recommended payable amount for review.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/construction-commercial
- Docs: https://www.brainiac.software/api/construction-commercial/docs
- OpenAPI: https://www.brainiac.software/api/construction-commercial/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/construction-commercial/contractor-payment-application-audit

$0.04 USDC. Independently check a contractor payment application against the schedule of values, measured work, approved variations, previous certificates, retention rules, and deductions. Unsupported claims, duplicated work, unapproved variations, retention errors, and certificate mismatches are adjusted with calculation evidence. The recommended payable amount is for review only.

Inputs: contract, schedule_of_values, payment_application, previous_certificates?, measured_work?, variations?, deductions?

Docs: https://www.brainiac.software/api/construction-commercial/docs#construction-commercial-contractor-payment-application-audit

Example request:

```json
{
  "contract": {
    "id": "c1",
    "currency": "GBP",
    "retention_bps": 500,
    "retention_release_bps": 10000
  },
  "schedule_of_values": [
    {
      "id": "sov-1",
      "description": "Foundations",
      "contracted_amount": 100000
    },
    {
      "id": "sov-2",
      "description": "Frame",
      "contracted_amount": 200000
    }
  ],
  "payment_application": {
    "id": "app-3",
    "application_number": 3,
    "submitted_on": "2026-11-05",
    "claimed_retention_release": 1000,
    "lines": [
      {
        "id": "l1",
        "sov_item_id": "sov-1",
        "claimed_amount": 40000,
        "previously_certified_amount": 50000
      },
      {
        "id": "l2",
        "sov_item_id": "sov-2",
        "claimed_amount": 25000
      },
      {
        "id": "l3",
        "sov_item_id": "sov-2",
        "claimed_amount": 10000,
        "variation_id": "var-1"
      }
    ]
  },
  "previous_certificates": [
    {
      "id": "cert-1",
      "certificate_number": 1,
      "certified_on": "2026-10-01",
      "retention_held": 2500,
      "lines": [
        {
          "sov_item_id": "sov-1",
          "certified_amount": 50000
        }
      ]
    }
  ],
  "measured_work": [
    {
      "id": "m1",
      "sov_item_id": "sov-1",
      "measured_amount": 80000
    },
    {
      "id": "m2",
      "sov_item_id": "sov-2",
      "measured_amount": 20000
    }
  ],
  "variations": [
    {
      "id": "var-1",
      "sov_item_id": "sov-2",
      "approved_amount": 8000,
      "approved": false,
      "description": "Extra steel"
    }
  ],
  "deductions": [
    {
      "id": "d1",
      "amount": 500,
      "reason": "Defects"
    }
  ]
}
```

Example response:

```json
{
  "currency": "GBP",
  "verified_lines": [
    {
      "application_line_id": "l1",
      "sov_item_id": "sov-1",
      "code": "claim_exceeds_measure_or_contract",
      "claimed_amount": 40000,
      "recommended_amount": 30000,
      "adjustment_amount": -10000,
      "evidence": [
        "measured_amount 80000, previously certified 50000, contracted_amount 100000.",
        "Allowable incremental amount is min(contracted-prior, measured-prior) = 30000.",
        "Claimed 40000 was reduced to 30000."
      ]
    },
    {
      "application_line_id": "l2",
      "sov_item_id": "sov-2",
      "code": "claim_exceeds_measure_or_contract",
      "claimed_amount": 25000,
      "recommended_amount": 20000,
      "adjustment_amount": -5000,
      "evidence": [
        "measured_amount 20000, previously certified 0, contracted_amount 200000.",
        "Allowable incremental amount is min(contracted-prior, measured-prior) = 20000.",
        "Claimed 25000 was reduced to 20000."
      ]
    },
    {
      "application_line_id": "l3",
      "sov_item_id": "sov-2",
      "code": "unapproved_variation",
      "claimed_amount": 10000,
      "recommended_amount": 0,
      "adjustment_amount": -10000,
      "evidence": [
        "Variation var-1 has approved=false, so the claimed amount is excluded."
      ]
    }
  ],
  "unsupported_claims": [],
  "duplicated_work": [],
  "variation_mismatches": [
    {
      "application_line_id": "l3",
      "variation_id": "var-1",
      "claimed_amount": 10000,
      "detail": "Variation is not marked approved."
    }
  ],
  "certificate_discrepancies": [],
  "retention": {
    "retention_bps": 500,
    "recommended_gross": 50000,
    "retention_held_this_period": 2500,
    "previous_retention_held": 2500,
    "retention_release": 1000,
    "calculation": "retention_held_this_period = floor(recommended_gross 50000 * retention_bps 500 / 10000) = 2500"
  },
  "deductions": {
    "items": [
      {
        "id": "d1",
        "amount": 500,
        "reason": "Defects"
      }
    ],
    "total": 500
  },
  "recommended_for_review": {
    "claimed_gross": 75000,
    "recommended_gross": 50000,
    "retention_held_this_period": 2500,
    "retention_release": 1000,
    "deductions_total": 500,
    "recommended_payable": 48000,
    "calculation": "recommended_payable = recommended_gross 50000 - retention 2500 + retention_release 1000 - deductions 500 = 48000"
  },
  "adjustments": [
    {
      "application_line_id": "l1",
      "sov_item_id": "sov-1",
      "code": "claim_exceeds_measure_or_contract",
      "claimed_amount": 40000,
      "recommended_amount": 30000,
      "adjustment_amount": -10000,
      "evidence": [
        "measured_amount 80000, previously certified 50000, contracted_amount 100000.",
        "Allowable incremental amount is min(contracted-prior, measured-prior) = 30000.",
        "Claimed 40000 was reduced to 30000."
      ]
    },
    {
      "application_line_id": "l2",
      "sov_item_id": "sov-2",
      "code": "claim_exceeds_measure_or_contract",
      "claimed_amount": 25000,
      "recommended_amount": 20000,
      "adjustment_amount": -5000,
      "evidence": [
        "measured_amount 20000, previously certified 0, contracted_amount 200000.",
        "Allowable incremental amount is min(contracted-prior, measured-prior) = 20000.",
        "Claimed 25000 was reduced to 20000."
      ]
    },
    {
      "application_line_id": "l3",
      "sov_item_id": "sov-2",
      "code": "unapproved_variation",
      "claimed_amount": 10000,
      "recommended_amount": 0,
      "adjustment_amount": -10000,
      "evidence": [
        "Variation var-1 has approved=false, so the claimed amount is excluded."
      ]
    },
    {
      "application_line_id": "app-3",
      "sov_item_id": "*",
      "code": "retention_release_accepted",
      "claimed_amount": 1000,
      "recommended_amount": 1000,
      "adjustment_amount": 0,
      "evidence": [
        "Claimed retention release 1000 is within held retention 2500."
      ]
    }
  ],
  "explanations": [
    "Non-variation lines require measured_work. Allowable incremental amount = min(contracted_amount - previously_certified, measured_amount - previously_certified).",
    "Variation lines require approved=true. Claims above approved_amount - previously_certified are capped.",
    "previously_certified is summed from previous_certificates lines for the same sov_item_id and optional variation_id.",
    "retention_held_this_period = floor(recommended_gross * retention_bps / 10000).",
    "Every adjustment includes calculation evidence. No unstated rates or quantities are invented."
  ]
}
```