{"openapi":"3.1.0","info":{"title":"GET /api/v1/credit/issuer/cardholders","version":"1.0.0","description":"List spend by cardholder"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/issuer/cardholders":{"get":{"tags":["credit"],"summary":"List spend by cardholder","description":"Card spend per cardholder on the Ramp account connected to this business, highest spend first: transactions, net spend, spend in the last 30 days, the cards used, the newest transaction and the credit lines the cards are registered to. Declined and errored transactions are not spend. Without `start` the window opens at the first stored transaction. `CREDIT_742` when `start` is after `end`.","operationId":"list_issuer_cardholders","parameters":[{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"First transaction date to include (inclusive, UTC).","title":"Start"},"description":"First transaction date to include (inclusive, UTC)."},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Last transaction date to include (inclusive, UTC).","title":"End"},"description":"Last transaction date to include (inclusive, UTC)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Page size (1 to 500).","default":100,"title":"Limit"},"description":"Page size (1 to 500)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` from the previous page, passed back unchanged.","title":"Cursor"},"description":"`next_cursor` from the previous page, passed back unchanged."},{"name":"include_total_count","in":"query","required":false,"schema":{"type":"boolean","description":"Also return `total`, the number of matching rows (one more query).","default":false,"title":"Include Total Count"},"description":"Also return `total`, the number of matching rows (one more query)."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_IssuerCardholderPage_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_issuer_cardholders_api_v1_credit_issuer_cardholders_get"}}},"components":{"schemas":{"IssuerCardholderItem":{"properties":{"cardholder_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cardholder Name","description":"The employee; null groups card transactions with no name."},"transaction_count":{"type":"integer","title":"Transaction Count","description":"Card transactions in the window (declined and errored excluded)."},"spend_cents":{"type":"integer","title":"Spend Cents","description":"Net card spend in the window, in cents: charges less refunds."},"last_30_days_spend_cents":{"type":"integer","title":"Last 30 Days Spend Cents","description":"Net card spend in the 30 days ending on `end` (today, UTC, when `end` is not sent), whatever `start` is."},"card_last_fours":{"items":{"type":"string"},"type":"array","title":"Card Last Fours","description":"Last four digits of the cards used in the window, sorted."},"last_transaction_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Last Transaction Date","description":"Date of the cardholder's newest transaction."},"credit_line_ids":{"items":{"type":"string"},"type":"array","title":"Credit Line Ids","description":"Credit lines on this business their cards are registered to."}},"type":"object","required":["cardholder_name","transaction_count","spend_cents","last_30_days_spend_cents"],"title":"IssuerCardholderItem","description":"Card spend by one cardholder over the window."},"IssuerCardholderPage":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass back as `cursor` for the next page. Null on the last."},"has_next":{"type":"boolean","title":"Has Next","description":"Another page follows. Looked up one row past the page, so a full last page is not reported as more.","default":false},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"The page size the list was read with."},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Row count; present only with `include_total_count=true`."},"items":{"items":{"$ref":"#/components/schemas/IssuerCardholderItem"},"type":"array","title":"Items","description":"The cardholders on this page."}},"type":"object","title":"IssuerCardholderPage","description":"Spend per cardholder, highest spend first."},"SuccessEnvelope_IssuerCardholderPage_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/IssuerCardholderPage"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[IssuerCardholderPage]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}