Read documents for your Telegram subscription bot or Discord subscription bot project.
API key access: Unrestricted project key required. There is no issuable documents:read API-key scope. Restricted keys cannot call this endpoint.
Returns 200 application/json with document metadata and an optional download_url. It can still succeed when no link can be produced. This endpoint does not return PDF bytes or an HTTP redirect. The separate file URL's content type and redirects are not established by this API contract.
Required, non-null fields: document_id (UUID string), kind (enum), filename (string, possibly empty), file_size (number of bytes), and created_at (UTC ISO datetime string).
kind is invoice, receipt, usage_report, credit_note, reverse_invoice, refund_note, or payout_statement.
Optional UUID-or-null fields: payment_request_id, invoice_id, project_id, and customer_id. project_name is an optional string-or-null. download_url is an optional URL string, never null; it is omitted when unavailable.
See document visibility rules for endpoint- and caller-specific denial behavior.
GET /v2/projects/ {project_id} /documents/ {document_id} /download Try it Authorization Bearer API Key Required
curl "https://api.botsubscription.com/v2/projects/11111111-1111-4111-8111-111111111111/documents/dddddddd-dddd-4ddd-8ddd-dddddddddddd/download" \ -H "Authorization: Bearer YOUR_API_KEY" Document metadata application/json
{ "ok" : true , "request_id" : "44444444-4444-4444-8444-444444444444" , "method" : "GET" , "path" : "/v2/projects/11111111-1111-4111-8111-111111111111/documents/dddddddd-dddd-4ddd-8ddd-dddddddddddd/download" , "code" : 200 , "data" : { "document_id" : "dddddddd-dddd-4ddd-8ddd-dddddddddddd" , "kind" : "invoice" , "filename" : "example-invoice.pdf" , "file_size" : 20480 , "created_at" : "2030-01-01T00:00:00.000Z" , "payment_request_id" : null , "invoice_id" : null , "project_id" : "11111111-1111-4111-8111-111111111111" , "customer_id" : null , "project_name" : "Example community" , "download_url" : "https://files.example.com/example-invoice.pdf" } } Download link unavailable application/json
{ "ok" : true , "request_id" : "44444444-4444-4444-8444-444444444444" , "method" : "GET" , "path" : "/v2/projects/11111111-1111-4111-8111-111111111111/documents/dddddddd-dddd-4ddd-8ddd-dddddddddddd/download" , "code" : 200 , "data" : { "document_id" : "dddddddd-dddd-4ddd-8ddd-dddddddddddd" , "kind" : "invoice" , "filename" : "example-invoice.pdf" , "file_size" : 20480 , "created_at" : "2030-01-01T00:00:00.000Z" , "payment_request_id" : null , "invoice_id" : null , "project_id" : "11111111-1111-4111-8111-111111111111" , "customer_id" : null , "project_name" : "Example community" } } UNAUTHORIZED application/json
{ "ok" : false , "request_id" : "44444444-4444-4444-8444-444444444444" , "method" : "GET" , "path" : "/v2/projects/11111111-1111-4111-8111-111111111111/documents/dddddddd-dddd-4ddd-8ddd-dddddddddddd/download" , "code" : 401 , "error" : { "error_code" : "UNAUTHORIZED" , "message" : "Invalid or expired authentication token." } } FORBIDDEN application/json
{ "ok" : false , "request_id" : "44444444-4444-4444-8444-444444444444" , "method" : "GET" , "path" : "/v2/projects/11111111-1111-4111-8111-111111111111/documents/dddddddd-dddd-4ddd-8ddd-dddddddddddd/download" , "code" : 403 , "error" : { "error_code" : "FORBIDDEN" , "message" : "Access is not permitted." } } NOT_FOUND application/json
{ "ok" : false , "request_id" : "44444444-4444-4444-8444-444444444444" , "method" : "GET" , "path" : "/v2/projects/11111111-1111-4111-8111-111111111111/documents/dddddddd-dddd-4ddd-8ddd-dddddddddddd/download" , "code" : 404 , "error" : { "error_code" : "NOT_FOUND" , "message" : "Requested resource could not be found" } } VALIDATION_ERROR application/json
{ "ok" : false , "request_id" : "44444444-4444-4444-8444-444444444444" , "method" : "GET" , "path" : "/v2/projects/11111111-1111-4111-8111-111111111111/documents/dddddddd-dddd-4ddd-8ddd-dddddddddddd/download" , "code" : 422 , "error" : { "error_code" : "VALIDATION_ERROR" , "message" : "Invalid request parameters." } } Request schema validation failed application/json
{ "ok" : false , "request_id" : "44444444-4444-4444-8444-444444444444" , "method" : "GET" , "path" : "/v2/projects/11111111-1111-4111-8111-111111111111/documents/not-a-uuid/download" , "code" : 422 , "errors" : [ { "error_code" : "VALIDATION_ERROR" , "message" : "params: document_id Invalid UUID" } ] } See API response formats and project API authentication .
