Partner API

A partner account on rates.now has an API key, an affiliate record for attribution, and a list of the lenders it may price and route leads to. Every call is server-to-server from your backend. Do not call the API from the browser: the key would be exposed, and your domain is not on our CORS allowlist.

1. Call GET /api/rates with the borrower's scenario. You get one entry per lender with priced quotes.
2. Show the quotes in your UI. Keep the entry's lenderId and the quote object the borrower selects.
3. Capture the borrower's contact details on your site.
4. Call POST /api/leads with the contact details, the lenderId, the selected quote and the scenario.
5. rates.now stores the lead, credits it to your affiliate, and delivers it to the lender's CRM through BankingBridge.

Send your key in the x-api-key header on every request. There is no session, cookie or OAuth flow.

x-api-key: YOUR_KEY

The key is shown once when it is created. Only a hash is stored, so a lost key cannot be recovered. Ask your rates.now contact to deactivate it and issue a new one. A key carries the scope of the account that owns it, so every key you hold prices the same lenders and attributes leads to the same affiliate.

Your account has a lender allowlist. GET /api/rates returns only those lenders, and POST /api/leads accepts only their lenderIdvalues. Some of them may be brands that do not appear on rates.now itself. A lead for any other lender is refused with 403 lender_not_available.

Lender ids are stable. Cache the id to name mapping from the rates response if you need it elsewhere, but always submit the id you received for the quote the borrower picked.

Returns priced quotes for one borrower scenario. Quotes are pre-generated and cached per scenario bucket, so the call is fast and the figures match what the lender quoted for that bucket.

Query parameters

Example request

curl "https://rates.now/api/rates?loanType=va&includeVA=true&loanTerm=30&loanAmount=450000&downPayment=0&propertyType=single_family_home&propertyUse=primary_home&creditScore=740&zipCode=78201" \
  -H "x-api-key: YOUR_KEY"

Example response

{
  "rates": [
    {
      "lenderId": 3,
      "brandId": "2033626",
      "lenderName": "Armed Forces Bank",
      "logo": "https://.../logo.png",
      "appLink": "https://...",
      "responseData": [
        {
          "productName": "VA 30 Yr Fixed",
          "rate": 5.875,
          "apr": 6.112,
          "pts": 0,
          "price": 100,
          "loanTerm": 30,
          "loanType": "VA",
          "lockPeriod": 30,
          "principalAndInterest": 2662,
          "monthlyMI": 0,
          "closingCost": 0,
          "quote_id": 58954412,
          "hash": "ee9c558834813caa8fb28d3b31b8be02"
        }
      ]
    }
  ],
  "metadata": {
    "scenarioHash": "8b41e76bca65c8c8",
    "isJumbo": false,
    "derivedState": "TX",
    "requestedLoanTypes": ["va"],
    "pricingRequestId": 2956
  }
}

Reading the response

• rates has one entry per visible lender that has quotes for the scenario. A lender with no quotes is omitted. An empty array is a valid answer.
• responseData lists the lender's quotes. rate and apr are percentages. pts is points as a percentage of the loan. principalAndInterest and monthlyMI are monthly dollars.
• metadata.pricingRequestId identifies this pricing call. Send it back on the lead.
• metadata.derivedState is set when the state came from the ZIP code. metadata.isJumbo is true when the amount is above the conforming limit.
• Quotes expire. Fetch fresh rates when the borrower returns rather than reusing a cached response for more than a few minutes.

Submits one borrower to one lender. The lead is stored, attributed to your affiliate, and delivered to the lender. Submit one request per lender when a borrower chooses to be shared with several, with the same submissionId and the matching shareCount on each.

Body fields

scenarioData keys

Use the same values the borrower priced with. These fill the lender's lead details, so the loan officer sees the scenario behind the quote.

Example request

curl -X POST https://rates.now/api/leads \
  -H "x-api-key: YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Jordan Rivera",
    "email": "jordan@example.com",
    "phone": "5125550142",
    "lenderId": 3,
    "selectedRateRawData": { "...the responseData item the borrower picked..." },
    "scenarioData": {
      "loanAmount": 450000, "downPayment": 0, "state": "TX", "zipCode": "78201",
      "creditScore": 740, "loanType": "va", "loanPurpose": "purchase",
      "propertyUse": "primary_home", "militaryEligible": "yes"
    },
    "pricingRequestId": 2956,
    "sourceUrl": "https://partner.example/va-rates",
    "shareCount": 1,
    "submissionId": "sub_8f3a2c",
    "attribution": { "campaign_id": "va-q4", "cost_per_lead": 7, "placement": "rates-widget" }
  }'

Response 201

{
  "message": "Lead created successfully",
  "lead": {
    "id": 4821,
    "lenderId": 3,
    "affiliateId": 12,
    "pricingRequestId": 2956,
    "shareCount": 1,
    "status": "new",
    "attribution": { "campaign_id": "va-q4", "cost_per_lead": 7, "placement": "rates-widget" },
    "bbLeadResponse": { "lead_id": 991203 }
  }
}

lead.id is the rates.now lead id. bbLeadResponse.lead_id is the lender-side id once the lead is delivered. Keep both for support questions.

Refused lead

{
  "message": "This lender is not available to the caller.",
  "code": "lender_not_available"
}

Every error is JSON with a message. Some carry a stable code.

1. Confirm the lenders in your allowlist with your rates.now contact.
2. Price a scenario for each loan type you plan to show and check the quotes render in your UI.
3. Submit a test lead and confirm the 201 response carries your attribution keys.
4. Ask your rates.now contact to confirm the test lead arrived in the lender's CRM, then delete it.
5. Store the key in your secret store and remove it from any test scripts.

Questions, new lenders or a replacement key: contact the rates.now team that set up your account.