Partner API

Overview

The GreyRok Partner API is how an aggregator, broker platform, introducer or lead generation partner sends a commercial finance application to GreyRok Capital and follows it to an outcome.

You never integrate with our CRM or our loan management system, and you never see anything beyond the applications you submitted yourself. Where an application lives once it reaches us, and which of our systems handles it, is ours to change without telling you.

Our published product is $5,000 to $500,000 for Australian businesses. Send us what your client actually asked for. A request above that range is accepted and assessed rather than refused at validation, because the decision belongs to a credit assessor and not to a schema. Accepting a submission is not an indication of the outcome, and it never has been.

Below $5,000 is still refused at validation, with a message you can show the broker. So is a figure that is not a plausible loan amount, which means above $25,000,000: that bound exists to catch a misplaced decimal, not to cap your deals.

• Synchronous validation. Every rule runs before we answer. A failure comes back as a list of fields with sentences written for a broker to read, not for a developer to translate.
• Your reference travels. The reference you send is stored against the application and returned on every message we send you afterwards, so attribution holds for the whole lifecycle.
• Safe to retry. Submissions are keyed on your reference. A repeat of one we already hold answers 409 and names the application, rather than creating a second one.

Getting started

Four steps, and the first two are ours.

1. Tell us you want to integrate. We agree the commercial terms, then issue your credentials.
2. Send us the https URL you want status updates posted to, and a secret we will send with each one so you can tell they are ours. Both can follow later; nothing about submitting depends on them.
3. Point your client at the sandbox base URL. Validation rules, error shapes and status payloads are documented below and are final.
4. Build and test against the sandbox, then swap the base URL and the key for the live ones. Two things change between environments and both are in the Environments table below: the base URL, and the document upload host. Nothing else in your configuration does.

There is a machine readable specification at /api/partner/openapi.json. If your tooling generates clients from OpenAPI, start there rather than from this page.

Authentication

Every request carries a partner key as a bearer token.

Authorization: Bearer grk_test_examplepartner_2f9c1d...

The key names the environment it belongs to, and a key presented to the wrong one is refused before anything is read. Until GreyRok completes its production cutover both base URLs accept grk_test_ keys, so the key alone does not keep a test deal out of the live credit queue: send test deals to the sandbox.

What a failure looks like

A missing credential is 401. A credential we do not recognise, one that has been revoked, and one from the other environment are all 403, and all give the same body. The three are not distinguished, because telling an unauthenticated caller which of those applies tells them something about keys they do not hold.

403 Forbidden

{
  "success": false,
  "data": {
    "error": "Invalid credentials"
  }
}

Rate limits

Submissions are limited to 300 per hour per partner unless your agreement says otherwise, which is set high enough that ordinary broker volume never meets it. It applies to POST /applications and to nothing else. Exceeding it answers 429 with a Retry-After of one hour. Wait for it rather than retrying immediately.

A request body over 256 KB is refused with 413 before it is read. That is generous for an application, including one carrying several directors, and it is a separate limit from the 25 MB per document on the upload endpoint.

Environments

The sandbox is a complete copy of the submission path. It validates identically and mints real references, and its schema is compared against production with a check GreyRok runs before a release.

Submit an application

Validates the application in full and creates it against your account. Money is in whole Australian dollars; an amount carrying cents is rounded to the nearest dollar rather than refused.

POST /api/partner/v1/applications
Authorization: Bearer grk_test_examplepartner_2f9c1d...
Content-Type: application/json

{
  "externalRef": "A7K92QF",
  "facility": {
    "amountRequested": 65000,
    "purpose": "cashflow",
    "guaranteeOffered": true
  },
  "business": {
    "abn": "33 051 775 556",
    "entityName": "Example Holdings Pty Ltd",
    "industry": "Retail",
    "tradingSince": "2019-03-14",
    "monthlyRevenue": 180000
  },
  "applicant": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "mobile": "0412 345 678"
  },
  "consent": {
    "obtained": true,
    "obtainedAt": "2026-09-11T04:12:00Z",
    "method": "broker_portal"
  },
  "documents": {
    "illionDocumentIds": [
      "A1B2C3D4E"
    ]
  }
}

201 Created

{
  "success": true,
  "reference": "GRK-1209-4471",
  "externalRef": "A7K92QF",
  "status": "Application with credit team",
  "receivedAt": "2026-09-12T02:14:08Z",
  "statementsRequired": true
}

Store the reference. It is how we and you name the same deal for the rest of its life, it appears on every status update, and it is what our credit team will quote if they call.

Retries and duplicates

externalRef must be unique within your account, and that is what makes a retry safe. If a request times out and you do not know whether it landed, send it again with the same reference. Either it was never recorded and is created now, or it was, and you get the reference we already hold.

409 Conflict

{
  "success": false,
  "error": "This reference has already been submitted.",
  "reference": "GRK-1209-4471",
  "externalRef": "A7K92QF"
}

Treat a 409 as success on the earlier attempt. Do not generate a new reference and resubmit: that is how one deal becomes two applications and two credit assessments.

Directors are optional

Send the directors array when you hold director detail and we will not ask the applicant for it again. Omit it entirely when you do not, and we collect it from the applicant directly. Send the array or omit it; an empty array is refused, because it asserts there are no directors rather than that you do not know them.

Who we call

Tell us who you would like our credit team to call about the application with whoToCall: client or broker. For a broker, send the broker block with their name and phone number. For the client, send callOnBehalfOf, the name you would like us to say we are calling on behalf of, as in “Hi, this is GreyRok calling on behalf of ABC Finance”. Either one missing is a 422 at that field.

All three are optional, and a submission without them is accepted as before. What you send is shown to our credit team as your request, in the email that tells them about a new application and on the deal they work from, along with any notes. It is a request to people, not a setting: we may still contact the applicant directly, for example to complete the full application.

Field reference

Every field, its type and its bounds. This table is generated from the same schema the endpoint validates with, so it cannot describe a rule the server does not enforce.

Consent

We cannot assess an application without the applicant having consented to us collecting, using and disclosing their personal and credit information for that purpose, including obtaining information about them from credit reporting bodies.

So consent.obtained must be true on every submission, and you tell us when and how consent was given. We record that as your assertion, with its timestamp and method, and rely on it under your partner agreement.

{
  "consent": {
    "obtained": true,
    "obtainedAt": "2026-09-11T04:12:00Z",
    "method": "broker_portal",
    "applicantIp": "203.0.113.42"
  }
}

applicantIp is optional and worth sending where you captured it. It is the difference between a record that says consent was obtained and one that can show where from.

Validation errors

A validation failure is 422 with one entry per field. Each error is a complete sentence written to be shown to a broker without rewording.

422 Unprocessable Content

{
  "success": false,
  "errors": [
    {
      "field": "facility.amountRequested",
      "error": "Our minimum facility is $5,000."
    },
    {
      "field": "business.abn",
      "error": "That ABN is not valid. Check for a mistyped digit."
    },
    {
      "field": "directors[1].dateOfBirth",
      "error": "Enter the date of birth as YYYY-MM-DD."
    }
  ]
}

field is a path in dot and bracket notation, so it maps onto an input in your own form. A field appears at most once, even when it breaks two rules, and the list follows the order the fields are documented above.

Every status code this API returns

200

The request succeeded.

201

The application or document was created.

400

The body was not readable as JSON.

401

No credentials were supplied.

403

Credentials were not recognised, revoked, or from the other environment.

404

No such application in your account, or the wrong host for this endpoint.

405

Wrong method. The upload endpoint takes POST only.

409

This external reference has already been submitted.

413

The body is over 256 KB, or the uploaded file is over 25 MB.

422

One or more fields failed validation.

429

Rate limited. Wait for Retry-After.

502

We could not record it. Safe to retry with the same reference.

503

Maintenance window. Wait for Retry-After and retry.

502 and 503 are the two to retry. Everything in the 400 range needs the request changed, and retrying it unchanged will fail the same way.

Check an application

Returns the current state of one application. Scoped to your own account: a reference belonging to another partner answers 404, exactly as a reference that does not exist does, so this endpoint cannot be used to find out whether a deal was placed somewhere else.

200 OK

{
  "success": true,
  "reference": "GRK-1209-4471",
  "externalRef": "A7K92QF",
  "status": "Approved",
  "statusGroup": "In Progress",
  "description": "Application approved by the GreyRok credit team.",
  "updatedAt": "2026-09-28T23:05:00Z",
  "requestedLoanAmount": 65000
}

A closed application also carries reason here, in the same words as the message that closed it, when our credit team recorded one. A declined or withdrawn message you missed loses nothing. A funded application carries approvedLoanAmount, the figure its funded message carried, when we hold one.

We push status updates, so this is a reconciliation tool rather than the intended pattern. Use it to catch up after an outage at your end, not as a polling loop.

Supporting documents

One file per request, as multipart form data. Send several requests to attach several documents.

POST https://qhjgawbbbrrcmlgvkwkj.supabase.co/functions/v1/partner-documents/applications/GRK-1209-4471/documents
Authorization: Bearer grk_test_examplepartner_2f9c1d...
Content-Type: multipart/form-data; boundary=...

file=@financials-fy26.pdf
documentType=Financial statements
description=FY26 profit and loss, prepared by the accountant

Documents may arrive during or after submission. A document sent for an application we have already decided is still accepted and still reaches the credit file, because a decision is not the end of a conversation.

Sending the same file twice is not an error. We fingerprint the contents, answer 201 with duplicate: true, and store one copy.

Bank statements

Where a broker has already collected bank statements through illion, send the illion document references on the submission itself rather than as files.

{
  "documents": {
    "illionDocumentIds": [
      "A1B2C3D4E"
    ]
  }
}

Statements are optional at submission. An application without them is accepted and assessed; we ask the applicant directly where we need them.

Status updates

We post a message to the URL you register with us whenever an application you submitted changes state. You do not poll.

One exception, for now. When your applicant completes the full application, the applicationUnderAssessment it produces is emailed to you and not posted. The same event is posted when it comes from our credit team.

POST https://your-platform.example.com/greyrok/status
Authorization: Bearer <the secret you gave us>
Content-Type: application/json

{
  "applicationId": "GRK-1209-4471",
  "externalRef": "A7K92QF",
  "status": "Settled",
  "statusName": "Funded",
  "eventType": "applicationFunded",
  "description": "Facility funded.",
  "lastModified": "2026-10-02T04:20:11Z",
  "companyTradingName": "Example Holdings Pty Ltd",
  "requestedLoanAmount": 65000,
  "approvedLoanAmount": 60000
}

Two levels of status, both sent

status is the group and statusName is the specific status within it. Both are sent on every message, because they are two levels of the same vocabulary and partners differ in which one they want to switch on. Use whichever suits you and ignore the other.

When an application closes

A declined or withdrawn message carries one more key, reason, when our credit team recorded why the application closed. It is a plain English sentence written for a broker to read, and it is absent when no reason was recorded.

POST https://your-platform.example.com/greyrok/status
Authorization: Bearer <the secret you gave us>
Content-Type: application/json

{
  "applicationId": "GRK-1809-3120",
  "externalRef": "C4N27TP",
  "status": "Rejected",
  "statusName": "Declined - Credit policy",
  "eventType": "applicationDeclined",
  "description": "Application declined.",
  "lastModified": "2026-09-24T06:31:52Z",
  "companyTradingName": "Example Freight Pty Ltd",
  "requestedLoanAmount": 120000,
  "reason": "Outside our lending criteria"
}

Switch on statusName, never on reason. The name comes from the published vocabulary below. The reason is written for people, and its wording may be improved without notice. Every name and reason we send is listed under Status vocabulary.

What a funded event does and does not carry

An applicationFunded event carries approvedLoanAmount, the amount the facility funded at in whole dollars, whenever we hold it. It can differ from requestedLoanAmount, because the amount can change while a deal is worked. GET returns the same figure while the application is funded.

The schema also allows the funded type, the fresh capital and three commission figures. Read those as optional, because today they are absent: the commission on a deal is agreed commercially and does not reach the system that sends these messages.

They are omitted rather than sent as zero. A zero is a number you would reconcile against, and it would be wrong. When the figures are available the keys appear, which needs no change at your end if you treat them as optional now.

How to know a message is from us

Give us a secret with your URL and we send it on every status update as a bearer token:

Authorization: Bearer <the secret you gave us>

Compare it with the secret you gave us before you act on a message. It is the secret itself, sent over HTTPS, and not a signature: the body is not signed. If you have given us no secret, no Authorization header is sent. A secret is 16 to 200 printable ASCII characters with no spaces.

To change it, send us the new one and accept both until messages arrive carrying the new one. A message you refuse is dropped, as Delivery below explains, so refusing the old secret too early loses updates.

While your endpoint is being set up we may send a test message. It carries "test": true, names no real application and has no externalRef, and it may carry your secret. Answer it 200 and discard it.

Delivery

Answer 200 as soon as you have stored the message, and do your own work afterwards. We wait ten seconds for a response and we do not follow redirects.

Only some failures are retried. A 5xx, a 408, a 429 and no response at all are retried. A message gets six attempts in all: the first, then retries after 5 minutes, 15 minutes, 1 hour, 4 hours and 12 hours. Retries are sent by a scheduled job, so one can arrive later than its interval.

• Expect duplicates. A retry can deliver a message you already have. applicationId together with eventType identifies a delivery, so make your handler idempotent on that pair.
• Do not assume every state arrives. Movement inside our own process that you cannot act on is not sent, so statuses can appear to skip. Treat each message as the current state rather than as one step along a known path.
• One message per event, ever. An application sends each eventType at most once, so a second transition that maps to an event you have already been sent produces nothing. That is the same pair your handler deduplicates on, enforced at our end as well as expected at yours.
• Timestamps are ISO 8601, in UTC. Not month first. If you are working from a sample payload that reads 08/21/2026, that is not what we send.

Email notifications

Every status change that produces a webhook also produces an email to your organisation, unless you have asked for webhook only (below). It is the same events and the same information, sent to a person rather than to a system, because most of the work on a deal is done by someone reading a mailbox.

Give GreyRok one address when you are onboarded, and tell us if it changes. A shared operations mailbox works better than an individual, for the same reason it does anywhere else.

What each email contains

• Your reference and ours, the business trading name, the amount requested, the status and when it changed, and on a funded application the amount it funded at, where we hold it. Nothing that is not already in the webhook payload for the same event.
• No commission figures. GreyRok does not hold them, so they are in neither the email nor the payload, including on a funded application.
• A reason when an application closes, where one was recorded. The same words the webhook carries as reason, listed under Status vocabulary.

If you give us no address, nothing is sent. That is a supported choice rather than a fault, and the webhook is unaffected. It is also silent, so if you expect these emails and are not getting them, the address is the first thing to check with us.

Webhook only. If you receive status updates at a webhook URL, ask us to stop the emails. That stops every further status email, including on applications already in progress, except applicationUnderAssessment when your applicant completes the full application, which is still emailed because it is not yet posted. It needs a webhook URL on file, so you always hear one way or the other.

Status vocabulary

These are the values GreyRok sends, the group each belongs to, and the event that produces it. The list is the same for every partner and changes only with a new version of this document, so build against it rather than against names agreed in conversation. A name you do not recognise still arrives with its group in status: fall back on that rather than refusing the message.

Your own platform may track states beyond these, covering work it does on a lead before it reaches us. GreyRok will not send those.

• Rejected is final. Once an application has closed as declined or withdrawn, nothing further is sent for it.
• Funded is final unless the facility is later lost. If a funded deal falls over, one Rejected message follows, and then nothing further. Do not close your record so firmly on Funded that it refuses the correction.

Why an application closed

A Rejected message names the most specific status we can give, and carries the reason our credit team recorded as reason. These are every pair we send.

Where no reason was recorded, reason is absent and the message carries the general name for its event: Declined - General on applicationDeclined or Client declined - No longer required on applicationWithdrawn.

Porting an existing integration

This API follows conventions you have probably met before: a 422 with field level messages rather than one sentence, your own reference carried through the whole lifecycle, and a separate endpoint for documents. That is deliberate. An integration you can port is cheaper for you than one you have to learn.

If you already submit to another lender, the field reference above is the authority. Three things are commonly different, and they are the three worth checking before you map anything.

Three differences worth knowing

Identifiers are names, not numbers. Where an API takes an industry or purpose id from a picklist, ours takes a string from a documented list. There is no lookup table to fetch and nothing to keep in sync.

One applicant, then directors, then the broker. Many APIs carry a single owner block for a person who may also be the guarantor. We separate them. applicantis the client’s contact, the person at the business we would speak to, who is not always a director. directors are the directors and guarantors. broker is the broker who introduced the deal, and is never the applicant.

A date, not a band. We take business.tradingSince as a date and work out the trading history ourselves, so there is no band for you to choose and no rounding for you to reason about.

OpenAPI document

The full specification is served as OpenAPI 3.1 at /api/partner/openapi.json. It is public, needs no credentials, and includes the outbound status update as an OpenAPI webhook so you can generate your receiving handler from it too.

It is generated from the same definitions that validate a live request, so it cannot drift from the running server. Version 1.3.0 is also returned in an x-partner-api-version header if you want to detect a change without parsing the document.

Breaking changes get a new path prefix. Everything under /api/partner/v1 keeps the shape documented here. New optional fields may be added to a response, and new eventType and statusName values may be added to the vocabulary, each with a new version number. Parse permissively, ignore a field you do not recognise, and handle a status you do not recognise by its status group rather than refusing it.

Support

Integration questions go to admin@greyrokcapital.com. Include your partner name and, where a specific application is involved, its GreyRok reference. Do not include a key.

If you are considering becoming a distribution partner and have not spoken to us yet, start at brokers and partners.