Ingest latest rental invoice

Fetch only the current month’s rental invoice from Gmail and upload it to S3.

POST /v1/invoices/{type}/ingest/latest

cURL

curl --request POST \
  --url https://api.paypulse.io/v1/invoices/rental/ingest/latest \
  --header 'Authorization: Bearer <token>'

201

{
  "message": "Invoice for 3/2025 found and ingested successfully!",
  "code": 201,
  "data": null
}

This endpoint is also triggered automatically by an EventBridge rule every weekday at 8:30 AM UTC. When invoked by EventBridge, it processes all registered users rather than a single authenticated user.

Authentication

All requests to this endpoint must include a valid JWT in the Authorization header.

Authorization: Bearer <token>

Path parameters

type · string · required

The invoice type. Must be rental for this endpoint.

What this endpoint does

This endpoint checks whether a rental invoice for the current calendar month already exists in DynamoDB. If not, it connects to the user’s Gmail account and searches for the latest rental invoice email for the current month and year. If found, the PDF attachment is downloaded and uploaded to S3.

The Gmail account must be connected before calling this endpoint. See Store Gmail tokens.

Response

message · string

A human-readable confirmation message describing the outcome:

• "Invoice for <month>/<year> found and ingested successfully!" — invoice was fetched and uploaded (HTTP 201).
• "Invoice for <month>/<year> has already been processed." — invoice already exists (HTTP 200).
• "Rental invoice for <month>/<year> has not been dispatched yet." — no matching email found in inbox (HTTP 204).

code · number

HTTP status code. 201 when a new invoice is ingested, 200 when already processed, 204 when not yet available.

data · null

Always null for this endpoint.

Error responses

Status	Error code	Description
400	INVALID_JSON	The request body is not valid JSON.
400	MISSING_FIELDS	A required key is missing from the request.
401	INVALID_CREDENTIALS	The Authorization header is missing or the OAuth token is invalid.
401	TOKEN_EXPIRED	The JWT has expired.
502	DEPENDENCY_FAILURE	The Gmail API or a downstream service returned an error.
500	INTERNAL_SERVER_ERROR	An unexpected server-side error occurred.

Error responses follow this structure:

{
  "error": {
    "code": "DEPENDENCY_FAILURE",
    "message": "Gmail API error"
  }
}

cURL

curl --request POST \
  --url https://api.paypulse.io/v1/invoices/rental/ingest/latest \
  --header 'Authorization: Bearer <token>'

201

{
  "message": "Invoice for 3/2025 found and ingested successfully!",
  "code": 201,
  "data": null
}