Reports
PDF and XLSX reports of a project's listings, prepared under your agency's name. Build one, wait until it is ready, and download it within 7 days.
Send include_logins: true to add the directory logins and their password, for your client to take over the accounts. Such a report never appears on a share link's page, and only a key with full permissions downloads it.
Starts building a PDF or XLSX report of the project's listings, prepared under your agency's name, with the directory logins when you send include_logins: true. Poll the report until status is ready, or wait for the report.ready event. Each project can start 1 PDF every 30 seconds and 1 XLSX every 10 seconds, and as many again with logins.
project_id*stringThe project's id.
^prj_[0-9A-Za-z]{22}$Idempotency-Key?stringA unique string, such as a UUID, that makes a retry safe. A success is kept for 24 hours: a repeat with the same key and body returns it again with Idempotent-Replayed: true, and the same key with another body returns 422 idempotency_key_reused. A repeat while the first request runs returns 409 idempotency_key_in_use. An error changes nothing, so a repeat after one runs again.
1 <= length <= 255application/json- body
The report to build.
format*stringpdf for a document to forward, xlsx for a spreadsheet with 1 row per listing.
"pdf""xlsx"include_logins?booleantrue to add the directory logins and the password they share: a page in the PDF, a sheet in the XLSX. Such a report never appears on a share link's page, and only a key with full permissions downloads its file. Defaults to false.
The report is building.
application/json- response
A PDF or XLSX report of a project's listings, prepared under your agency's name.
object*stringAlways report.
id*stringThe report's id.
^rep_[0-9A-Za-z]{22}$livemode*booleantrue for a live project, false for a test project. Test reports are a sample marked TEST MODE.
project*stringThe project's id.
^prj_[0-9A-Za-z]{22}$format*stringThe file format.
"pdf""xlsx"include_logins?booleantrue when the file includes the directory logins and their password: only a key with full permissions downloads it.
status*stringbuilding, then ready or failed. A failed report sends report.failed; build a new one.
"building""ready""failed"file_name*|The file's name, once ready. null otherwise.
created_at*stringWhen you asked for the report.
date-timeready_at*|When the file was ready. null until then.
date-timeexpires_at*|When the file is deleted, 7 days after ready_at. null until the file is ready.
date-timeTypical errors
curl -X POST "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/reports" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY" \ -H "Idempotency-Key: 4f9d2c1e-ledgerly-create" \ -H "Content-Type: application/json" \ -d '{"format":"pdf"}'{ "object": "report", "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "pdf", "include_logins": false, "status": "building", "file_name": null, "created_at": "2026-10-08T15:02:10Z", "ready_at": null, "expires_at": null}Returns the report and its status. Once status is ready, download the file from GET /reports/{report_id}/file until expires_at.
report_id*stringThe report's id.
^rep_[0-9A-Za-z]{22}$The report.
application/json- response
A PDF or XLSX report of a project's listings, prepared under your agency's name.
object*stringAlways report.
id*stringThe report's id.
^rep_[0-9A-Za-z]{22}$livemode*booleantrue for a live project, false for a test project. Test reports are a sample marked TEST MODE.
project*stringThe project's id.
^prj_[0-9A-Za-z]{22}$format*stringThe file format.
"pdf""xlsx"include_logins?booleantrue when the file includes the directory logins and their password: only a key with full permissions downloads it.
status*stringbuilding, then ready or failed. A failed report sends report.failed; build a new one.
"building""ready""failed"file_name*|The file's name, once ready. null otherwise.
created_at*stringWhen you asked for the report.
date-timeready_at*|When the file was ready. null until then.
date-timeexpires_at*|When the file is deleted, 7 days after ready_at. null until the file is ready.
date-timeTypical errors
curl "https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY"{ "object": "report", "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP", "livemode": false, "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", "format": "pdf", "include_logins": false, "status": "ready", "file_name": "ledgerly-listings-2026-10-08.pdf", "created_at": "2026-10-08T15:02:10Z", "ready_at": "2026-10-08T15:02:41Z", "expires_at": "2026-10-15T15:02:41Z"}Returns the PDF or XLSX file of a ready report. Files are kept for 7 days; after expires_at this returns 410 gone, and you build a new report. A file with logins is credentials: a read-only key gets 403 permission_denied for it.
report_id*stringThe report's id.
^rep_[0-9A-Za-z]{22}$The file, with a Content-Disposition that names it.
response?fileThe PDF report.
binarycurl "https://api.submitator.com/v1/reports/rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP/file" \ -H "Authorization: Bearer $SUBMITATOR_API_KEY""string"