▣ DEVELOPER TOOLS · FILE MANIPULATION

Split Excel API

Hosted on ApyHub

What it does

Excel Splitter takes one or more .xlsx or .xlsm files and splits each workbook into separate outputs based on the values in a chosen column. Send the files, plus a 1-based sheet index and 1-based target column index for each file, and you get a batch of split jobs back.

Use it when you need to break a workbook into per-customer, per-region, per-team, or per-category files without doing the sorting manually. The response includes a batch_id and a jobs array with each job's job_id, filename, status, progress, sheet_index, and target_column_index, so you can track work at the file level.

Poll /status/:job_id to check a single split job or batch, or use /overall-status with multiple job IDs to aggregate progress across them. When a job is finished, download the output workbook from /download/:job_id as binary content.

Excel Splitter is a file automation tool for workflows where spreadsheets need to be partitioned consistently and repeated often.

▣ ENDPOINT 01 / 04

POST

Split Excel files into one workbook per value group in a column

https://api.eu.apyhub.com/flowdocs/split-excel

QUICKSTART

GUIDE

Quickstart

Upload one or more Excel files to start a split job.

curl -X POST "https://api.eu.apyhub.com/flowdocs/split-excel" \
  -H "apy-token: $APY_TOKEN" \
  -F "files=@/path/to/report.xlsx"

What you'll get back

Returns a JSON object with a batch_id string and a jobs array. Each job is an object with job_id, filename, status, and progress, and may also include batch_id, sheet_index, and target_column_index.

{
  "batch_id": "a1b2c3d4e5f6a7b8",
  "jobs": [
    {
      "job_id": "a1b2c3d4",
      "filename": "report.xlsx",
      "status": "queued",
      "progress": 0
    }
  ]
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Splits each uploaded Excel file into separate workbooks based on the values found in a chosen column on a chosen sheet. The response returns a batch identifier and a list of child jobs created for the split operation.

Request Body

Parameter	Type	Mandatory	Description
files	String Array	Yes	Excel files to split. Accepted file types: `.xlsx`, `.xlsm`.
sheet_index	String Array	No	Sheet number per uploaded file, 1-based. Provide one value per file.
target_column_index	String Array	No	Column number to split by per uploaded file, 1-based. Provide one value per file.

Response

Returns a JSON object with a required batch_id string field and a required jobs array field. Each item in jobs is an object describing a child job, including job_id, filename, status, progress, and, when present, batch_id, sheet_index, and target_column_index.

Parameter	Type	Mandatory	Description
batch_id	String	Yes	Parent batch id for the split operation.
jobs	Object Array	Yes	Child jobs created for the batch. Each item includes `job_id`, `filename`, `status`, and `progress`, and may also include `batch_id`, `sheet_index`, and `target_column_index`.
jobs[].job_id	String	Yes	Identifier of the child job.
jobs[].filename	String	Yes	Filename associated with the child job.
jobs[].status	String	Yes	Status of the child job.
jobs[].progress	Integer	Yes	Progress value for the child job.
jobs[].batch_id	String	No	Parent batch id this child belongs to.
jobs[].sheet_index	Integer	No	Sheet index used for the source file, 1-based.
jobs[].target_column_index	Integer	No	Target column index used to split the file, 1-based.

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 02 / 04

GET

Get the status of an Excel split job

https://api.eu.apyhub.com/flowdocs/split-excel/status/:job_id

QUICKSTART

GUIDE

Quickstart

Check the status of a split-excel-files job by replacing :job_id with your job ID in the endpoint URL.

curl -X GET "https://api.eu.apyhub.com/flowdocs/split-excel/status/:job_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object. The response is one of three shapes: a batch status object with job_id, batch, status, progress, total_files, completed_files, and jobs; a parent batch reference with job_id, batch_id, status, and progress; or a single job status object with job_id, status, and progress.

{
  "job_id": "job_12345",
  "status": "processing",
  "progress": 50
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns the current status of an Excel split job. The response shape depends on whether the job_id refers to a batch job, a child job in a batch, or a standalone job.

Path Parameter(s)

Attribute	Type	Mandatory	Description
job_id	String	Yes	The job identifier in the `/status/:job_id` path.

Response

Returns a JSON object describing job state. The exact top-level fields depend on the matched schema variant, but all variants include job_id, status, and progress; some also include batch-related fields and an optional error string.

Parameter	Type	Mandatory	Description
job_id	String	Yes	The job identifier. In the batch variant, this is described as the batch id.
status	ENUM	Yes	Job status. Allowed values: `queued`, `processing`, `done`, `failed`.
progress	Integer	Yes	Progress percentage from 0 to 100.
batch	Boolean	Yes (if batch response variant)	Present in the batch response variant. Allowed value: `true`.
total_files	Integer	Yes (if batch response variant)	Total number of files in the batch.
completed_files	Integer	Yes (if batch response variant)	Number of files completed so far.
jobs	Object Array	Yes (if batch response variant)	List of child jobs in the batch. Each item includes: `job_id` (`String`), `status` (`String`), `progress` (`Integer`).
error	String	No	Error message, when provided by the response variant.
batch_id	String	Yes (if child-job response variant)	Parent batch id. Billing happens at the parent, not here.

Path parameters

Name

Type

Description

job_idREQUIRED

string

—

▣ ENDPOINT 03 / 04

GET

Download a finished Excel split output

https://api.eu.apyhub.com/flowdocs/split-excel/download/:job_id

QUICKSTART

GUIDE

Quickstart

Download the split Excel file for a completed job by replacing job_id in the path.

curl -X GET "https://api.eu.apyhub.com/flowdocs/split-excel/download/:job_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns the binary file contents directly, not a JSON object. The response schema is a string with format: "binary".

<binary file data>

TRY ITLIVE · 5 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Downloads the finished output file for a completed Excel split job. The request uses the job_id in the path and the response is the binary file content itself.

Path Parameter(s)

Attribute	Type	Mandatory	Description
job_id	String	Yes	Identifies the finished split job to download.

Response

Returns a binary response body (string with binary format) containing the downloaded Excel split output file.

Attribute	Type	Mandatory	Description
body	String	Yes	Binary file content for the finished split output.

Path parameters

Name

Type

Description

job_idREQUIRED

string

—

▣ ENDPOINT 04 / 04

GET

Aggregate progress across Excel split jobs

https://api.eu.apyhub.com/flowdocs/split-excel/overall-status

QUICKSTART

GUIDE

Quickstart

Check the overall status for one or more split jobs by passing the required job_ids query parameter.

curl -X GET "https://api.eu.apyhub.com/flowdocs/split-excel/overall-status?job_ids=job-123,job-456" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with required status and progress fields, plus optional details, total_files, and completed_files.

status is a string (unknown, queued, processing, done, or failed)
progress is an integer from 0 to 100
details is an array of objects with job_id, status, and progress
total_files and completed_files are integers

{
  "status": "processing",
  "progress": 60,
  "details": [
    {
      "job_id": "job-123",
      "status": "processing",
      "progress": 60
    }
  ],
  "total_files": 2,
  "completed_files": 1
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns the aggregate progress for one or more Excel split jobs. Provide the job ID(s) in the query string to get an overall status, overall progress, and per-job details.

Query Parameter(s)

Attribute	Type	Mandatory	Description
job_ids	String	Yes	Job ID(s) to aggregate.

Response

Returns a JSON object with status and progress as required top-level fields. It may also include details, total_files, and completed_files to provide per-job and summary progress information.

Parameter	Type	Mandatory	Description
status	ENUM	Yes	Overall job status. Allowed values: `unknown`, `queued`, `processing`, `done`, `failed`.
progress	Integer	Yes	Overall progress as a percentage from 0 to 100.
details	Object Array	No	Per-job progress details. Each item may include:<br>- `job_id` (String)<br>- `status` (String)<br>- `progress` (Integer)
total_files	Integer	No	Total number of files across the split jobs.
completed_files	Integer	No	Number of files that have been completed.

Query parameters

Name

Type

Description

job_idsREQUIRED

string

—

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.