API Integration
API Endpoints
Complete reference for all FoxCalc funder API endpoints
All endpoints are prefixed with /api/v1/{funder} where {funder} is your funder slug (e.g., fox).
Create Offer
POST /api/v1/{funder}/offersCreates a new offer and returns a signed calculator URL.
Scopes required: offers:create
Request Body
{
"deal_id": "DEAL-001",
"merchant_name": "Acme Corp",
"merchant_id": "M-12345",
"merchant_state": "NY",
"iso_name": "Best ISO",
"iso_id": "ISO-789",
"deal_type": "new_deal",
"brand_id": "your-brand-uuid",
"initial_status": "active",
"position": 1,
"purchase_price_floor": 10000,
"purchase_price_ceiling": 50000,
"default_purchase_price": 25000,
"buy_rate": 1.20,
"max_upsell": 0.10,
"default_upsell": 0.05,
"holdback_pct": 0.15,
"monthly_receivables": 100000,
"existing_funding_balance": 0,
"base_frequency": "daily",
"available_frequencies": ["daily", "weekly"],
"num_payments_floor": 60,
"num_payments_ceiling": 252,
"default_num_payments": 126,
"payment_amount_override": 500,
"payment_override_behavior": "ceiling",
"fees": [
{
"id": "origination",
"label": "Origination Fee",
"amount": 0.03,
"amount_type": "pct",
"visible": true,
"adjustable": false
},
{
"id": "wire",
"label": "Wire Fee",
"amount": 50,
"amount_type": "fixed",
"visible": true,
"adjustable": false
}
],
"fee_config": { "show_fee_breakdown": true },
"prepayment_schedule_mode": "auto_generate",
"prepayment_config": {
"model": "step_per_month",
"params": {
"rate_step": 0.02,
"floor_term_months": 3
}
},
"display_config": {
"show_prepayment_schedule": true,
"show_stipulations": true,
"show_fee_breakdown": true
},
"stipulations": [
"3 months bank statements",
"Government-issued ID",
"Voided check"
],
"notification_emails": ["deals@yourcompany.com"],
"assigned_users": ["underwriter@yourcompany.com"],
"callback_url": "https://yourcompany.com/webhooks/foxcalc",
"funder_notes": "Priority deal — expedited review"
}Response (201)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"deal_id": "DEAL-001",
"version": 1,
"status": "active",
"calculator_url": "/DEAL-001?sig=abc123&exp=1700000000"
}Required vs Optional Fields
| Field | Required | Default |
|---|---|---|
deal_id | Yes | — |
merchant_name | Yes | — |
iso_name | Yes | — |
purchase_price_floor | Yes | — |
purchase_price_ceiling | Yes | — |
buy_rate | Yes | — |
max_upsell | Yes | — |
base_frequency | Yes | — |
available_frequencies | Yes | — |
num_payments_floor | Yes | — |
num_payments_ceiling | Yes | — |
brand_id | No | Funder's default brand |
holdback_pct | No | 0 |
existing_funding_balance | No | 0 |
fees | No | [] |
fee_config | No | { show_fee_breakdown: false } |
prepayment_schedule_mode | No | none |
display_config | No | All false |
stipulations | No | [] |
initial_status | No | active |
callback_url | No | Uses brand's default |
Replace Offer
PUT /api/v1/{funder}/offers/{dealId}Full replacement of an existing offer. Requires optimistic concurrency via version.
Scopes required: offers:update
{
"version": 1,
"merchant_name": "Acme Corp",
"purchase_price_floor": 15000,
"purchase_price_ceiling": 60000,
"buy_rate": 1.22
}Response (200)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"deal_id": "DEAL-001",
"version": 2,
"status": "active",
"calculator_url": "/DEAL-001?sig=def456&exp=1700100000"
}Patch Offer
PATCH /api/v1/{funder}/offers/{dealId}Partial update — only send changed fields. Requires version.
Scopes required: offers:update
{
"version": 2,
"purchase_price_ceiling": 75000,
"max_upsell": 0.15
}Revoke Offer
DELETE /api/v1/{funder}/offers/{dealId}Revokes an offer. The calculator URL will no longer work.
Scopes required: offers:delete
Response (200)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"deal_id": "DEAL-001",
"status": "revoked"
}Optimistic Concurrency
All update operations (PUT, PATCH) require the current version number. If the version doesn't match (another update happened first), the API returns 409 Conflict. Fetch the latest version and retry.
Prepayment Models
Three prepayment schedule modes are supported:
Step-Per-Month (auto-generated)
{
"prepayment_schedule_mode": "auto_generate",
"prepayment_config": {
"model": "step_per_month",
"params": {
"rate_step": 0.02,
"floor_term_months": 3
}
}
}Generates a tier for every month from the estimated term down to floor_term_months. Factor rate decreases by rate_step per month.
Fixed Windows
{
"prepayment_schedule_mode": "auto_generate",
"prepayment_config": {
"model": "fixed_windows",
"params": {
"windows": [
{ "months_after_funding": 3, "factor_rate_discount": 0.10 },
{ "months_after_funding": 6, "factor_rate_discount": 0.05 },
{ "months_after_funding": 9, "factor_rate_discount": 0.02 }
]
}
}
}Funder-Provided (pass-through)
{
"prepayment_schedule_mode": "funder_provided",
"prepayment_schedule": [
{
"label": "At 3 months",
"termOrWindow": 3,
"factorRate": 1.06,
"amountSold": 26500,
"savings": 3500,
"discountPts": 14
}
]
}