Contractor Payment Application Audit API Documentation

POSThttps://www.brainiac.software/api/v1/construction-commercial/contractor-payment-application-audit$0.04 USDC

Audit contractor payment applications

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.

Body

Field	Required	Notes
`contract`	Yes	object; Object
`schedule_of_values`	Yes	array; Array
`payment_application`	Yes	object; Object
`previous_certificates`	No	array; Array
`measured_work`	No	array; Array
`variations`	No	array; Array
`deductions`	No	array; Array

Request exampleJSON

{
  "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"
    }
  ]
}

Response exampleJSON

{
  "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."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/construction-commercial/contractor-payment-application-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'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"
    }
  ]
}
JSON