Create an analysis job
/bsa/jobsQueue one or more statement PDFs for analysis. Returns 202 with the queued job.
- Auth
- API key or dashboard session token
- Request body
- JSON
Parameters
- filesarray · required
1 to 50 statement PDFs. Unknown fields are rejected.
- files[].storage_pathstring · required
Path of a PDF already stored in your organization's Paperwork document storage. It must start with your organization ID or the API key owner's user ID.
- files[].original_filenamestring · required
File name only, ending in .pdf.
- files[].size_bytesinteger · required
File size. Up to 25 MiB per file, 250 MiB per job.
- company_profile_idstring (UUID) · optional
Saved company profile used to recognise own accounts and related parties.
- company_contextobject · optional
Inline profile instead of a saved one: profile_id, legal_entity {entity_id, name}, and optional lists own_accounts, key_members, parent_companies, subsidiaries, sister_companies, other_related_entities. Cannot be sent together with company_profile_id.
- classification_modestring · optional
auto (default): uncertain points get a cautious default. review: they wait for a person.
- requested_monthsstring[] · optional
1 to 36 consecutive months as YYYY-MM. The report is cut to these months and names the ones with no statement.
- subjectstring · optional
business (default) or individual. individual adds the applicant report: salary, debt payments, debt burden and signals.
- applicantobject · optional
Individual only: declared_monthly_income, declared_income_basis (net or gross, default net), credit_card_limits [{issuer, limit}] and card_limit_rate (default 0.05). Can also be set later with the applicant endpoint.
| Name | Type | Required | Description |
|---|---|---|---|
| files | array | Yes | 1 to 50 statement PDFs. Unknown fields are rejected. |
| files[].storage_path | string | Yes | Path of a PDF already stored in your organization's Paperwork document storage. It must start with your organization ID or the API key owner's user ID. |
| files[].original_filename | string | Yes | File name only, ending in .pdf. |
| files[].size_bytes | integer | Yes | File size. Up to 25 MiB per file, 250 MiB per job. |
| company_profile_id | string (UUID) | No | Saved company profile used to recognise own accounts and related parties. |
| company_context | object | No | Inline profile instead of a saved one: profile_id, legal_entity {entity_id, name}, and optional lists own_accounts, key_members, parent_companies, subsidiaries, sister_companies, other_related_entities. Cannot be sent together with company_profile_id. |
| classification_mode | string | No | auto (default): uncertain points get a cautious default. review: they wait for a person. |
| requested_months | string[] | No | 1 to 36 consecutive months as YYYY-MM. The report is cut to these months and names the ones with no statement. |
| subject | string | No | business (default) or individual. individual adds the applicant report: salary, debt payments, debt burden and signals. |
| applicant | object | No | Individual only: declared_monthly_income, declared_income_basis (net or gross, default net), credit_card_limits [{issuer, limit}] and card_limit_rate (default 0.05). Can also be set later with the applicant endpoint. |
Example request
curl -X POST https://api.paperwork.to/api/v1/bsa/jobs \
-H "Authorization: Bearer sk-paperwork-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"files": [
{
"storage_path": "YOUR_ORG_ID/statements/example-jan-mar.pdf",
"original_filename": "example-jan-mar.pdf",
"size_bytes": 482113
}
],
"classification_mode": "auto",
"requested_months": ["2026-01", "2026-02", "2026-03"]
}'Example response
{
"job_id": "5b0d7c1e-0000-4000-8000-000000000001",
"parent_job_id": null,
"status": "QUEUED",
"progress": { "stage": "VALIDATING", "percent": 0, "message": null },
"documents": [],
"result": null,
"error": null,
"password_request": null
}- This endpoint does not take file bytes or URLs. Ask us to set up storage access when you get your API key.
- Status values: QUEUED, PROCESSING, NEEDS_INPUT, COMPLETED, FAILED, CANCELLED.
- 400, 404 PROFILE_NOT_FOUND, 403 STORAGE_OBJECT_FORBIDDEN, 422 INVALID_REQUEST and 503 QUEUE_UNAVAILABLE are possible.