Skip to main content
CURL
Try it live: PDF to CSV → API Tester — send a real request from your browser.

POST /v1/pdf/convert/to/csv

Quick start

A request containing only url is enough to start a conversion.
To see the request size limits, please refer to the Request Size Limits.

Request body

Attributes are case-sensitive and should be inside JSON for POST request. for example: { "url": "https://example.com/file1.pdf" } No query parameters accepted.
string
required
URL to the source file url attribute
string
The callback URL (or Webhook) used to receive the POST data. see Webhooks & Callbacks. This is only applicable when async is set to true.
string
HTTP auth user name if required to access source URL.
string
HTTP auth password if required to access source URL.
string
Specify page indices as comma-separated values or ranges to process (e.g. “0, 1, 2-” or “1, 2, 3-7”). The first-page index is 0. Use ”!” before a number for inverted page numbers (e.g. “!0” for the last page). If not specified, the default configuration processes all pages. The input must be in string format.
boolean
default:"false"
Unwrap lines into a single line within table cells in provided PDF documents. This is only applicable when lineGrouping is set to 1.
string
Defines coordinates for extraction. UsePDF Edit Add Helperto get or measure PDF coordinates. The format is {x} {y} {width} {height}.
string
default:"eng"
Set the language for OCR (text from image) to use for scanned PDF, PNG, and JPG documents input when extracting text. see Language Support. You can also use 2 languages simultaneously like this: eng+deu (any combination).
boolean
default:"false"
Set to true to return results inside the response. Otherwise, the endpoint will return a URL to the output file generated.
string
Controls how lines of text are grouped when extracting data from a PDF. Line grouping within table cells. The available modes are: 1, 2, 3. For more information, see Line Grouping.
Line Grouping Options
  • "1": GroupByRows – Each row is checked against the next row to see if they can be grouped together. Rows will only be grouped if all cells in the current row can be grouped with all cells in the next row. Useful when merging related content that spans multiple lines but belongs to the same logical row.
  • "2": GroupByColumns – Each cell is checked against the cell below it in the next row to determine if they can be grouped. Cells are grouped within the same column even if others can’t be grouped. Useful for columnar data where content in each column might span multiple lines.
  • "3": JoinOrphanedRows – Joins a row with a single cell to the previous row if there is no separator between them. Useful for handling cases with orphaned or misaligned content.
string
Password for the PDF file.
boolean
default:"false"
Set async to true for long processes to run in the background, API will then return a jobId which you can use with the Background Job Check endpoint. Also see Webhooks & Callbacks
string
File name for the generated output, the input must be in string format.
integer
default:"60"
Set the expiration time for the output link in minutes. After this specified duration, any generated output file(s) will be automatically deleted from PDF.co Temporary Files Storage. The maximum duration for link expiration varies based on your current subscription plan. To store permanent input files (e.g. re-usable images, pdf templates, documents) consider using PDF.co Built-In Files Storage.
string
See Profiles for more information.Pass profiles as a string containing serialized JSON, not as a JSON object. The subparameters below are settings inside that string, not separate request-body fields.

Responses

To see the main response codes, please refer to the Response Codes page.

Synchronous URL output

Omit inline and async, or set both to false, to return the final CSV URL. The Quick start and primary sample requests use this mode. Omitting async uses its default of false.
Synchronous URL response

Inline CSV output

Set inline: true and async: false to return CSV text in body.
Inline CSV response

Asynchronous submission

Set async: true to run conversion in the background. This CSV path returns jobId and a reserved output URL, including when inline: true. Use Background Job Check and download the result only after the job succeeds. The initial response does not include body or pageCount.
Asynchronous request
Asynchronous submission response

Timeout behavior

Synchronous CSV conversion can time out. Use async: true for long-running requests. The gateway returns HTTP 408 for an upstream request timeout and maps conversion-service timeout code 445 to HTTP 408. A gateway transport timeout has no status field; a conversion-service timeout can retain numeric status: 445 while errorCode is 408. The gateway upstream timeout defaults to 35 seconds and can vary by deployment. For asynchronous requests, duration measures submission handling. Background Job Check reports the completed job duration separately as jobDuration.
Inconsistent URL Encoding in cURL Output: When using cURL to make API requests, the output JSON may show URL characters encoded as Unicode escape sequences. For example, the ampersand character (&) may appear as \u0026 in the cURL output. This is normal JSON encoding behavior and does not affect the validity of the URL. The URL will function correctly when used, as JSON parsers automatically decode these escape sequences. If you’re parsing the response programmatically, your JSON parser will handle this conversion automatically.

Upload workflow examples

These examples upload a local file before converting it to CSV.