POST /receipts/extract

POST

Submit Receipt for Asynchronous Extraction

Production API: https://api.heypeppy.ai/v1Sandbox / Staging: https://staging-api.heypeppy.ai/v1Interactive Mock Server: https://mock.heypeppy.ai/v1

/receipts/extract

Submits a receipt PDF or image for asynchronous processing. The API immediately enqueues the job into Google Cloud Tasks with tenant isolation and returns a `202 Accepted` response containing a `jobId` and `pollUrl`. Once extraction completes, Peppy sends an HMAC-signed webhook to your configured `webhookUrl` or makes the result available via `GET /jobs/{jobId}`.

Headers

HTTP Headers

Parameter	Type	Description
Authorizationrequired	string	Bearer token format: Bearer <API_KEY> Example: Bearer pep_live_99281a8b
X-Tenant-IDoptional	string	B2B Tenant identifier (e.g., stepup, odyssey, classwallet). If omitted, inferred from API key context. Example: stepup
Content-Typerequired	string	application/json Example: application/json

Query Parameters

URL Query String

Parameter	Type	Description
priorityoptional	string default: standard	Queue priority level for enterprise SLAs (standard or high). Allowed values: standardhigh Example: standard
validateOnlyoptional	boolean default: false	If true, validates request payload and pre-signed file accessibility without enqueueing an extraction task. Example: false

Request Body

application/json

Field	Type	Description
fileUrlrequired	string (URI)	Public or pre-signed storage URL to the receipt image (JPEG, PNG, HEIC, WebP) or PDF file. Example: https://storage.googleapis.com/partner-uploads/receipt_1029.pdf
fileNameoptional	string	Original name of the uploaded file for logging and reporting reference. Example: receipt_1029.pdf
fileTypeoptional	string	MIME type of the uploaded file. Example: application/pdf
webhookUrloptional	string (URI)	HTTPS endpoint to receive a POST webhook notification upon job completion or failure. Example: https://portal.partner.org/api/webhooks/peppy
tenantIdoptional	string	Optional B2B tenant identifier (can also be passed via X-Tenant-ID header). Example: stepup
categorizeItemsoptional	boolean	Whether to execute purchasing policy audit & guideline categorization on extracted line items. Defaults to false. Example: true
programKeyoptional	string	Target scholarship program guideline rules (PEP, UA, FTC-FES-EO) for item categorization. Example: PEP
studentCandidatesoptional	array<StudentCandidate>	List of registered students in the family/account to automatically match receipt beneficiary.
↳idrequired	string	Unique student identifier in partner portal.
↳namerequired	string	Student display name.
↳officialNameoptional	string	Full legal name on scholarship account.
↳gradeLeveloptional	string	Grade level for eligibility checks.
↳scholarshipProgramoptional	string	Program code (e.g. PEP).

Responses

4 status codes

202 AcceptedReceipt extraction job successfully enqueued in the Cloud Tasks queue.

{
  "jobId": "job_01HXYZ1234",
  "tenantId": "stepup",
  "status": "queued",
  "pollUrl": "https://api.heypeppy.ai/v1/jobs/job_01HXYZ1234",
  "estimatedWaitMs": 5000
}

Interactive Test Console

Target ServerProduction API (https://api.heypeppy.ai/v1)Sandbox / Staging (https://staging-api.heypeppy.ai/v1)Interactive Mock Server (https://mock.heypeppy.ai/v1)

API Key (Authorization)

Bearer

X-Tenant-ID Headeroptional

Query Parameters

priority(none)standardhigh

validateOnly

Request Body (JSON)

{ "tenantId": "stepup", "fileUrl": "https://storage.googleapis.com/partner-uploads/kumon_receipt_4421.pdf", "fileName": "kumon_receipt_4421.pdf", "fileType": "application/pdf", "webhookUrl": "https://portal.partner.org/api/webhooks/peppy", "categorizeItems": true, "programKey": "PEP", "studentCandidates": [ { "id": "stu_1002", "name": "Emma Davis", "officialName": "Emma Grace Davis", "gradeLevel": "5th Grade", "scholarshipProgram": "PEP" } ] }

Mock Simulation Mode