Ingest rental invoices

Fetch all rental invoice PDFs from the user’s connected Gmail account and upload them to S3.

POST /v1/invoices/{type}/ingest

cURL

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

200 (invoices found)

{
  "message": "Rental invoices ingested successfully!",
  "code": 200,
  "data": {
    "invoiceCount": 3
  }
}

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 connects to the user’s Gmail account via the stored OAuth tokens, searches for rental invoice emails matching the configured sender and subject, and uploads any previously unseen invoice PDF attachments to S3. It skips invoices for months that have already been processed.

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

Response

message · string

A human-readable confirmation message. Example: "Rental invoices ingested successfully!" or "No rental invoices found for this user."

code · number

HTTP status code. 200 on success.

data · object | null

null when no new invoices were found. Otherwise contains the fields below.

Hide properties

invoiceCount · number

Number of new rental invoices ingested during this request.

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 returned an error.
502	GMAIL_TOKEN_EXPIRED	The Gmail OAuth refresh token has expired and the account must be re-connected.
500	INTERNAL_SERVER_ERROR	An unexpected server-side error occurred.

Error responses follow this structure:

{
  "error": {
    "code": "GMAIL_TOKEN_EXPIRED",
    "message": "Gmail account needs to be re-connected"
  }
}

cURL

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

200 (invoices found)

{
  "message": "Rental invoices ingested successfully!",
  "code": 200,
  "data": {
    "invoiceCount": 3
  }
}