Skip to main content

Quickstart Guide

Get up and running with the HeyPeppy API in minutes.

1. Authentication & Multi-Tenancy​

Enterprise partners receive separate keys for staging and production:

  • Sandbox: hp_test_...
  • Production: hp_live_...

Include your API key as a Bearer token, and specify your tenant identifier via the X-Tenant-ID header (or pass "tenantId": "..." in the JSON body):

Authorization: Bearer hp_live_your_api_key_here
X-Tenant-ID: your_tenant_id

2. Submit a Receipt for Extraction (cURL)​

Send a POST request with the file URL of the receipt PDF or image:

curl -X POST "https://api.heypeppy.com/v1/receipts/extract" \
  -H "Authorization: Bearer hp_live_your_api_key_here" \
  -H "X-Tenant-ID: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://storage.partner.org/receipts/kumon_receipt_1029.pdf",
    "fileName": "kumon_receipt_1029.pdf",
    "fileType": "application/pdf",
    "webhookUrl": "https://portal.partner.org/api/webhooks/peppy",
    "studentCandidates": [
      {
        "id": "stu_1002",
        "name": "Emma Davis",
        "officialName": "Emma Grace Davis"
      }
    ]
  }'

Response (202 Accepted)​

{
  "jobId": "job_01HXYZ1234",
  "tenantId": "your_tenant_id",
  "status": "queued",
  "pollUrl": "https://api.heypeppy.com/v1/jobs/job_01HXYZ1234",
  "estimatedWaitMs": 6000
}

3. Poll for Job Results​

If you are not using webhooks, poll the pollUrl until the job status becomes completed:

curl -X GET "https://api.heypeppy.com/v1/jobs/job_01HXYZ1234" \
  -H "Authorization: Bearer hp_live_your_api_key_here" \
  -H "X-Tenant-ID: your_tenant_id"

Response (200 OK)​

{
  "jobId": "job_01HXYZ1234",
  "tenantId": "your_tenant_id",
  "status": "completed",
  "attempts": 1,
  "timing": {
    "queuedAt": "2026-09-11T19:50:00Z",
    "startedAt": "2026-09-11T19:50:01Z",
    "completedAt": "2026-09-11T19:50:05Z",
    "durationMs": 4120
  },
  "result": {
    "vendor": "Kumon Math & Reading Center",
    "amount": 180.00,
    "transactionDate": "2026-09-02",
    "invoiceType": "service",
    "items": [
      {
        "description": "Monthly Math Tutoring - September 2026",
        "price": 180.00,
        "quantity": 1
      }
    ],
    "paymentDetails": {
      "isPaid": true,
      "paymentMethod": "Visa ending in 4128",
      "cardLast4": "4128",
      "proofOfPaymentType": "card"
    },
    "studentDetails": {
      "detectedStudentName": "Emma Davis",
      "matchedChildId": "stu_1002",
      "matchedChildName": "Emma Grace Davis",
      "matchConfidence": 95
    },
    "auditResult": {
      "summary": "Document contains valid proof of payment.",
      "isServiceBased": true,
      "isUnpaidInvoice": false,
      "hasLineItems": true,
      "hasTransactionDate": true,
      "hasProviderName": true,
      "hasTotalPrice": true,
      "hasPaidIndication": true
    }
  }
}

4. Run an Audit on a Submission Package​

Pass the submission context (merchant, line items, justifications, and program key) to receive an immediate compliance evaluation:

curl -X POST "https://api.heypeppy.com/v1/submissions/audit" \
  -H "Authorization: Bearer hp_live_your_api_key_here" \
  -H "X-Tenant-ID: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "Florida Virtual School",
    "amount": 325.00,
    "programKey": "FL_PEP",
    "lineItems": [
      {
        "description": "Algebra 1 Honors Full Curriculum Course",
        "price": 325.00,
        "category": "Curriculum/Course",
        "type": "Online",
        "detail": "High School",
        "justification": "Full year 9th grade high school math curriculum for Emma to satisfy academic course requirements."
      }
    ],
    "supportingFiles": [
      { "name": "flvs_algebra1_syllabus.pdf" }
    ],
    "async": false
  }'

Result​

{
  "confidenceScore": 92,
  "overallStatus": "pass",
  "summary": "This submission meets all core program requirements and is ready to submit.",
  "receiptFormat": {
    "isValid": true,
    "summary": "All required receipt format elements are present.",
    "missingFields": []
  },
  "purchaseLimitations": {
    "hasLimitations": false,
    "summary": "No purchase frequency or dollar limits apply to these items.",
    "limitations": []
  },
  "supportingDocumentation": {
    "hasRequirements": true,
    "summary": "All required supporting documentation is attached/linked.",
    "requiredDocuments": [
      {
        "documentType": "Course Syllabus",
        "isAttached": true,
        "status": "attached"
      }
    ]
  },
  "justificationAnalysis": [
    {
      "lineItemIndex": 0,
      "strength": "strong",
      "reason": "Justification clearly articulates the educational purpose and benefit for the student.",
      "improvementHints": []
    }
  ]
}