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

  • 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
                }

Updated 19 days ago