Documentation

Customer Search

Quickly check if a customer has a Koalafi application in progress and whether they can continue with financing.

Prerequisites

  • Endpoints:

    Sandbox: https://application-edge-service.sandbox.koalafi.com/query
Production: https://application-edge-service.koalafi.com/query

  • Headers (required on every request):

    public-dealer-id: <your-public-dealer-id>
private-api-key: <your-private-api-key>

What this does

This playbook consists of a series of API calls that searches for a customer and returns:

  • orderId (creates one if you don’t pass it)
  • customers (basic name match)
  • eligibility (includes canContinueWithKoalafi, displayText, and optional offer details)

On a successful match, the response header will include X-Hybrid-Token for seamless UI handoff.

Choose your input style

Option A — Phone + last 4 SSN (taxIDLast4)
Use if you only have partial SSN.

Option B — Phone + full SSN (taxId) + date of birth
Use if you have full PII for a stronger lookup.

Request shape (GraphQL)

This is the structure of the customers query use in the curl requests below:

query customers($input: CustomerSearchInput!) {
  customer(input: $input) {
    orderId
    customers { firstName lastName }
    eligibility {
      displayText
      canContinueWithKoalafi
      offerDetails {
        maxApprovalAmount
        approvalLanguage
        recurringPaymentDetails {
          paymentFrequency
          paymentDetails { leaseTerm paymentAmount }
        }
      }
    }
    customerSearchErrors {
      __typename
      ... on BadRequest { message }
      ... on NotFound { message }
      ... on FatalError { message }
    }
  }
}

A) Phone + Last 4 (Happy Path: App in Progress)

$ curl -sS https://application-edge-service.sandbox.koalafi.com/query     -H "public-dealer-id: <your-public-dealer-id>"     -H "private-api-key: <your-private-api-key>"     -H "Content-Type: application/json"     -d '{
"operationName": "customerSearch",
"query": "query customers($input: CustomerSearchInput!) { customer(input: $input) { orderId customers { firstName lastName } eligibility { displayText canContinueWithKoalafi offerDetails { maxApprovalAmount approvalLanguage recurringPaymentDetails { paymentFrequency paymentDetails { leaseTerm paymentAmount } } } } customerSearchErrors { __typename ... on BadRequest { message } ... on NotFound { message } ... on FatalError { message } } } }",
"variables": {
"input": {
"cellPhone": "7723845920",
"taxIDLast4": "2340"
}
}
}'
▶ Run Request
HTTP/1.1 200 OK
X-Hybrid-Token: HYB-abc123.def456

{
"data": {
"customer": {
"orderId": "2c402775-893d-4f8f-a5a0-e4a8aba8e42a",
"customers": [{ "firstName": "Koala", "lastName": "Tester" }],
"eligibility": {
"displayText": "Congratulations! You are prequalified for Koalafi's lease-to-own financing of up to $3,000.",
"canContinueWithKoalafi": true,
"offerDetails": {
"maxApprovalAmount": "3000",
"approvalLanguage": "prequalified",
"recurringPaymentDetails": [{
"paymentFrequency": "monthly",
"paymentDetails": [{ "leaseTerm": "12", "paymentAmount": "216.56" }]
}]
}
},
"customerSearchErrors": []
}
}
}

What this means

  • canContinueWithKoalafi: true → You can go ahead and open the Koalafi modal.
  • Include the X-Hybrid-Token header when you call your openModal() flow.

B) Phone + Full SSN + DOB (No App in Progress)

$ curl -sS https://application-edge-service.sandbox.koalafi.com/query     -H "public-dealer-id: <your-public-dealer-id>"     -H "private-api-key: <your-private-api-key>"     -H "Content-Type: application/json"     -d '{
"operationName": "customerSearch",
"query": "query customers($input: CustomerSearchInput!) { customer(input: $input) { customers { firstName lastName } eligibility customerSearchErrors { __typename } } }",
"variables": {
"input": {
"cellPhone": "3325554691",
"taxId": "110334691",
"birthDate": "1999-01-01"
}
}
}'
▶ Run Request
HTTP/1.1 200 OK

{
"data": {
"customer": {
"customers": [],
"eligibility": null,
"customerSearchErrors": []
}
}
}

What this means

  • No app is in progress. Direct the customer to start a new application.

Optional: Pass your own orderId

$ curl -sS https://application-edge-service.sandbox.koalafi.com/query     -H "public-dealer-id: <your-public-dealer-id>"     -H "private-api-key: <your-private-api-key>"     -H "Content-Type: application/json"     -d '{
"operationName": "customerSearch",
"query": "query customers($input: CustomerSearchInput!) { customer(input: $input) { orderId eligibility { canContinueWithKoalafi offerDetails { recurringPaymentDetails { paymentFrequency paymentDetails { leaseTerm paymentAmount } } } } } }",
"variables": {
"input": {
"orderId": "b5c0d6e0-1111-2222-3333-abc123abc123",
"cellPhone": "7723845920",
"taxIDLast4": "2340"
}
}
}'
▶ Run Request
HTTP/1.1 200 OK

{
"data": {
"customer": {
"orderId": "b5c0d6e0-1111-2222-3333-abc123abc123",
"eligibility": {
"canContinueWithKoalafi": true,
"offerDetails": {
"recurringPaymentDetails": [
{ "paymentFrequency": "monthly", "paymentDetails": [{ "leaseTerm": "12", "paymentAmount": "216.56" }] }
]
}
}
}
}
}

Tip: If you don’t pass orderId, we’ll create one and return it in the response.

Common error scenarios

App in progress with another merchant

$ curl -sS https://application-edge-service.sandbox.koalafi.com/query     -H "public-dealer-id: <your-public-dealer-id>"     -H "private-api-key: <your-private-api-key>"     -H "Content-Type: application/json"     -d '{
"operationName": "customerSearch",
"query": "query customers($input: CustomerSearchInput!) { customer(input: $input) { eligibility customerSearchErrors { __typename } } }",
"variables": {
"input": {
"cellPhone": "5551234567",
"taxIDLast4": "9999"
}
}
}'
▶ Run Request
HTTP/1.1 200 OK

{
"errors": [{
"message": "unauthorized dealer",
"path": ["customer","eligibility"],
"extensions": {
"canContinueWithKoalafi": false,
"displayText": "In progress application found with another merchant please call Koalafi Business Support at 844-238-6500"
}
}],
"data": { "customer": { "eligibility": null, "customerSearchErrors": [] } }
}

What to do: Ask the customer to call Koalafi Business Support to transfer the app.

Customer already completed a lease (Docs Signed)

$ curl -sS https://application-edge-service.sandbox.koalafi.com/query     -H "public-dealer-id: <your-public-dealer-id>"     -H "private-api-key: <your-private-api-key>"     -H "Content-Type: application/json"     -d '{
"operationName": "customerSearch",
"query": "query customers($input: CustomerSearchInput!) { customer(input: $input) { eligibility } }",
"variables": {
"input": {
"cellPhone": "5558887777",
"taxIDLast4": "1111"
}
}
}'
▶ Run Request
HTTP/1.1 200 OK

{
"errors": [{
"message": "Applicant has an application in 'Docs Signed'. Not eligibile for new app at this time",
"path": ["customer","eligibility"],
"extensions": {
"canContinueWithKoalafi": false,
"displayText": "Your lease agreement has already been signed and your order may have been placed by the merchant. Please contact the merchant to initiate a return or call Koalafi customer support at 844-937-8275"
}
}],
"data": { "customer": { "eligibility": null } }
}

What to do: Customer cannot open a new app. Direct to merchant support or Koalafi support.

Invalid credentials (401)

$ curl -sS https://application-edge-service.sandbox.koalafi.com/query     -H "public-dealer-id: WRONG"     -H "private-api-key: WRONG"     -H "Content-Type: application/json"     -d '{
"operationName": "customerSearch",
"query": "query customers($input: CustomerSearchInput!) { customer(input: $input) { orderId } }",
"variables": {
"input": {
"cellPhone": "7723845920",
"taxIDLast4": "2340"
}
}
}'
▶ Run Request
HTTP/1.1 401 Unauthorized

{
"errors": [{
"message": "UnAuthorized",
"path": ["order"]
}],
"data": null
}

Forbidden (403)

$ curl -sS https://application-edge-service.sandbox.koalafi.com/query     -H "public-dealer-id: <your-public-dealer-id>"     -H "private-api-key: <your-private-api-key>"     -H "Content-Type: application/json"     -d '{
"operationName": "customerSearch",
"query": "query customers($input: CustomerSearchInput!) { customer(input: $input) { orderId } }",
"variables": {
"input": {
"cellPhone": "bad",
"taxIDLast4": "bad"
}
}
}'
▶ Run Request
HTTP/1.1 403 Forbidden

{
"errors": [{
"message": "forbidden to access resource",
"path": ["order"]
}],
"data": null
}