Form 1003 API

Submit an application

curl -X POST https://paramountls.com/api/v1/loan-applications \
  -H 'content-type: application/json' \
  -d '{
    "submitted_by": { "agent_name": "Your Assistant" },
    "acknowledgments": { "borrower_consent_obtained": true },
    "borrowers": [{
      "first_name": "Marisol", "last_name": "Arredondo",
      "cell_phone": "(818) 412-7730", "email": "marisol@example-not-reserved.com"
    }],
    "loan": { "purpose": "purchase", "loan_amount": 680000 },
    "property": { "street": "482 N Maple St", "city": "Glendale", "state": "CA", "zip": "91206" }
  }'

That is the minimum. The full form has around 200 fields and every one of them is optional except those. Send what the borrower told you and nothing more.

Endpoints

Endpoint	What it returns
GET /api/v1	This API in one JSON object: endpoints, limits, the consent rule.
GET /api/v1/schema	The 1003 as JSON Schema, draft 2020-12.
GET /api/v1/programs	Loan programs with the enum value for each.
GET /api/v1/example	A filled example body. Carries dry_run: true, so submitting it as-is files nothing.
GET /api/v1/health	Whether the service can deliver mail right now. Names only, never values.
POST /api/v1/loan-applications	Files an application. 201 with an application id.

The full specification is at /openapi.json, OpenAPI 3.1, generated from the same declaration the validator uses — so it cannot drift from what the endpoint actually accepts.

What comes back

Code	Meaning
201	Filed. The body carries application_id and who it reached.
200	Dry run. Valid, previewed, deliberately not filed.
422	Either validation failed — the body names every field and what is wrong with it — or the borrower data is placeholder.
429	Rate limited. 12 requests a minute, and 20 filed applications a day, per address. Dry runs are exempt from the daily cap.
503	Nothing was recorded. Always safe to retry.

A 503 means the application was valid but could not be emailed to a loan officer. We answer 503 rather than 201 on purpose, so your agent never reports a filing that did not happen.

Filing twice by accident

Send an Idempotency-Key header. A repeat with the same key returns the first response again, marked idempotent_replay, and files nothing new. Retry loops are safe.

curl -X POST https://paramountls.com/api/v1/loan-applications \
  -H 'idempotency-key: your-own-unique-string' ...

Test without filing anything

Add "dry_run": true to the body. The application is validated, screened and rendered, then thrown away. Nothing is emailed, no application id is issued, and no loan officer is interrupted.

{ "dry_run": true, "submitted_by": { ... }, "borrowers": [ ... ] }

Use this to check a body before you commit to it. The example at /api/v1/example already carries the flag, so copying it files nothing.

Real submissions are screened for placeholder data. A borrower named Test, an @example.com address, a 555-0100 phone number or a Social Security number in a range the SSA never issues all come back 422 looks_like_test_data. That is not a filter on who may apply. It is a filter on data that describes nobody.

Validation, and why it is strict

A 422 lists every problem at once, each with the field path and what is wrong, so your agent can fix them in one turn rather than discovering them one at a time.

{
  "ok": false,
  "error": "validation_failed",
  "errors": [
    { "field": "loan.purpose", "message": "is required" },
    { "field": "borrowers.0.ssn", "message": "expected 9 digits" }
  ],
  "schema_url": "https://paramountls.com/api/v1/schema"
}

Phone numbers, SSNs, ITINs and ZIPs are normalised on the way in, so send them however the borrower gave them to you. Unknown fields are ignored with a warning rather than refused, so a newer client never breaks against an older form.

The one rule

acknowledgments.borrower_consent_obtained must be true, and it must be true in fact. File only for a borrower who knows you are filing and agreed to it.

Do not invent borrower data. Leave a field out rather than guessing it — the schema marks very little as required, and a loan officer would rather call and ask than read a confident wrong number. Every email we send says the identity behind the submission is unverified, because it is.

What you are sending

A 1003 carries a Social Security number, income and an address. Send it only with the borrower's knowledge, over HTTPS, and read the privacy policy first. The SSN field exists because the form has one — leave it out and a loan officer will ask the borrower directly.

Building something that files at volume? Email tom@paramountls.com before you launch it.

What this is not

• Not a rate quote. No rates, no pricing, no approval odds are returned. Nothing here prices a loan.
• Not a pre-approval or a credit decision. Filing obligates neither side.
• Not a credit pull. Nobody is checked until a loan officer has spoken to the borrower.

Paramount Loan Services is First Franklin Realty Inc, a licensed California mortgage broker, NMLS #236355. Licensed in California only. Equal Housing Opportunity. Verify the licence at NMLS Consumer Access.

Other ways in

• MCP — the mortgage MCP server, four tools over streamable HTTP.
• A2A — JSON-RPC at /a2a, agent card at /.well-known/agent-card.json.
• The overview page covers all three.