Quick Start

Send a personal loan application from your system and get matched offers back. An application is built in five steps, the same steps as the RateMatch form, then matched.

Before you start

You need your sandbox key, rm_sandbox_…, from RateMatch. This guide uses the sandbox server, https://staging.api.ratematch.ai/api/partner/v1, where credit checks are simulated and no credit bureau is called.
Every request sends the key as Authorization: Bearer …. See Authentication.
Keep keys on your server. Never put them in a web page or mobile app.

1. Create the application (step 1)

curl -X POST https://staging.api.ratematch.ai/api/partner/v1/applications \
  -H "Authorization: Bearer rm_sandbox_your_key" \
  -H "Idempotency-Key: 6f1c2b0e-create-1" \
  -H "Content-Type: application/json" \
  -d '{
    "formType": "personal",
    "data": { "loanAmount": 25000 }
  }'

201 Created

{ "success": true, "data": { "applicationId": "3f2c9a1e-8b4d-4c7e-9f1a-2b6d8e0c4a7f" } }

Keep the applicationId. The loan type (formType) is fixed from here on. The Idempotency-Key makes a retry return this response instead of creating a second application; use a new value for each new request.

2. Save steps 2, 3 and 4

One call per step, in order. Personal loans:

curl -X PATCH https://staging.api.ratematch.ai/api/partner/v1/applications/APPLICATION_ID \
  -H "Authorization: Bearer rm_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "step": 2, "data": { "loanPurpose": "holiday", "loanTerm": 3 } }'

Then the same call with these bodies for steps 3 and 4:

Request bodies

{ "step": 3,
  "data": { "employmentType": "full_time", "employmentYears": 3, "grossMonthlyIncome": 7000 } }

{ "step": 4,
  "data": { "livingSituation": "renting", "monthlyRent": 2200, "residentialYears": 2, "dependents": 0 } }

Car and home loans have different fields at steps 1–4. Every field, with allowed values, is in Application steps.

3. Submit applicant details and run the credit check (step 5)

curl -X POST https://staging.api.ratematch.ai/api/partner/v1/applications/APPLICATION_ID/credit-check \
  -H "Authorization: Bearer rm_sandbox_your_key" \
  -H "Idempotency-Key: 6f1c2b0e-credit-1" \
  -H "X-Sandbox-Score: high" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "firstName": "Jo", "lastName": "Citizen",
      "email": "jo@example.com", "mobileNumber": "0412345678",
      "dateOfBirth": "1985-06-15",
      "streetNumber": "1", "streetName": "George", "streetType": "St",
      "suburb": "Sydney", "state": "NSW", "postcode": "2000",
      "consentCreditCheck": true, "privacyConsent": true, "consentTerms": true
    }
  }'

200 OK

{ "success": true, "data": { "applicationId": "3f2c9a1e-…", "creditCheckComplete": true, "degraded_mode": false, "sandbox_mode": true } }

Consent is required. Only send consentCreditCheck: true when the applicant has agreed to a soft credit check in your journey. Without it the call is rejected and no check runs. Consent fields are JSON booleans: "true" or 1 is rejected too.

Live, this runs a soft check with Equifax. The response confirms the check ran; credit scores are not returned to partners. Always send an Idempotency-Key here, so a retry can't run a second check. In the sandbox, X-Sandbox-Score picks the simulated result (see Sandbox testing).

4. Get matched offers

curl -X POST https://staging.api.ratematch.ai/api/partner/v1/applications/APPLICATION_ID/match \
  -H "Authorization: Bearer rm_sandbox_your_key"

data.acceptedOffers are the offers the applicant qualifies for, each with the lender, a headline and offerDetails such as the rate. data.nearMissOffers narrowly missed, with the reasons and what would qualify. Matching again later (after changing a step, say) is fine.

5. Send the applicant to the offer they choose

Redirect the applicant's browser to the offer's trackingUrl. It records the referral against your partner account and forwards them to the lender. The link expires after a couple of hours, so match again rather than storing it.

Errors and retries

Errors look like { "success": false, "error": "VALIDATION_ERROR", "message": "…" }. Branch on error; a 400's message names the field, for example loanAmount: Number must be greater than or equal to 1000. Every code is in the API reference.
An application that isn't yours, or doesn't exist, returns 404.
Sending a step again replaces it.
With an Idempotency-Key, retrying after a timeout is safe: if the first request succeeded you get its response back (marked Idempotency-Replayed: true) rather than a second application or credit check. A 4xx releases the key, so fix the request and retry with it. A 409 IDEMPOTENCY_IN_PROGRESS means the first request is still running; retry shortly. After a 5xx, or a 409 IDEMPOTENCY_KEY_UNRESOLVED, the first request may have partly gone through: check the application before trying again with a new key.
Each key may make 120 requests a minute. Past that you get 429 with a Retry-After header.
GET /applications/APPLICATION_ID returns the application's status and last step. Every response has an X-Request-Id; quote it if you contact us.

Every field for every step API reference