Documentation
Start typing to search…

Customer Search

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

Prerequisites

  • Endpoint (Sandbox): https://application-edge-service.sandbox.koalafi.com/query

  • Headers required on every request:

    • public-dealer-id: <your-public-dealer-id>
    • private-api-key: <your-private-api-key>
    • Content-Type: application/json

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
            }

Updated 2 days ago