Data types

The data types of inputs and outputs (numbers, text, yes/no values, ranges) and how dates are handled: what a caller sends for each and what comes back.

The types

Every parameter has a Data Type (Datentyp), which you see and change in its dialog:

When you add a cell, the type is suggested from the value in the cell: a number gives Number, TRUE or FALSE gives Boolean, everything else String. A range is always Array (Range). There is no separate type for dates; see "Dates" below.

For an input the type is a rule: a value that does not fit is refused before anything is calculated. For an output the type describes what the cell normally returns.

Numbers

Sending. Send a number with a point as the decimal separator and without thousands separators.

Percentages are numbers sent as decimals, 0.05 for 5%; see Percentages and formats. A minimum, a maximum and a list of allowed values can limit a number; see Input validation.

Returning. A number comes back as a JSON number with the full precision of the cell, not rounded to the displayed decimals. To return a rounded value, use ROUND in the workbook.

Text

Sending. Any text. If the input has allowed values, the text must be one of them; spaces at the beginning and end and upper and lower case do not matter, unless the input is set to case-sensitive.

Returning. Text comes back as a JSON string.

Text that looks like a number, such as the postal code 01234, needs care in a GET call: values in the address are read as numbers where possible, and the leading zero is lost. Send such values with POST as a JSON string, "01234".

Yes/no values

Sending. A Boolean input accepts several spellings:

Upper and lower case do not matter. Anything else is refused: Expected a boolean, got: … Accepted values: true/false, yes/no, 1/0, wahr/falsch, ja/nein. The cell receives TRUE or FALSE.

Returning. A cell that holds TRUE or FALSE comes back as true or false.

Dates

Parameters have no date type. A date is sent and returned as text or as a number, and the workbook does the conversion. This keeps the format under your control.

Sending a date. The recommended way:

1. Make the input a String input.
2. Let callers send the date as text in the form 2026-03-01 (year-month-day).
3. In the workbook, convert it in a helper cell with =DATEVALUE(B1) and let your date formulas read from the helper cell.

The helper cell holds a real date, so comparisons such as =C1>DATE(2026,1,1) and functions such as EDATE or NETWORKDAYS work as expected. Do not compare the text cell itself with a date.

Alternatively, make the input a Number input and let callers send Excel's serial number for the date (46082 for 1 March 2026).

Returning a date. For a fixed, readable form, return text: put =TEXT(C5,"yyyy-mm-dd") into the output cell. The caller then always receives a text such as "2026-03-31".

Without TEXT, a date cell comes back as its stored value, which depending on the formula is a date-time text in ISO form or Excel's serial number. An output added from a date-formatted cell carries the format marker date in formatString.

Ranges

A range output comes back as a list of rows, each row a list of cell values. Each cell value follows the rules above, and an empty cell is null. A plain range has the size you selected; a range on a formula that fills several cells has the size the formula fills for each call. See Add outputs.

Inputs are always single cells. To pass several values, use several inputs.

Empty values and errors

GET and POST

POST carries the inputs as JSON, so each value has its JSON type:

{ "inputs": { "amount": 20000, "rate": 0.05, "customer": "ACME GmbH", "express": true } }

GET carries the inputs in the address, where everything is text. SpreadAPI reads true and false as yes/no values, text that is a number as a number, and everything else as text:

GET https://spreadapi.io/api/v1/services/{serviceId}/execute?amount=20000&rate=0.05&customer=ACME%20GmbH&express=true

Either way the value is then checked against the data type of its input. Encode special characters in a GET address (a space is %20). For details of both methods see Call the API.

For developers and agents

• Input names are matched without regard to case.
• A type error answers HTTP 400 with "error": "Parameter validation failed" and an entry of "type": "type_mismatch" carrying expectedType and receivedValue.
• In OpenAPI terms the input types are number, string and boolean; allowed values appear as enum. See OpenAPI and interactive docs.

FAQ

Which data types can an input have?

Number, String (text) and Boolean (yes/no). The type is suggested from the value in the cell and can be changed in the input's dialog under Data Type.

How do I send a date to my service?

Make the input a String input and send the date as text, 2026-03-01. In the workbook, convert it with =DATEVALUE(B1) in a helper cell and let your formulas use that cell.

How do I get a date back in a fixed format?

Return it as text: put =TEXT(C5,"yyyy-mm-dd") into the output cell. The caller then receives a text such as "2026-03-31".

How do I send yes or no?

For a Boolean input send true or false. yes/no, 1/0 and the German ja/nein and wahr/falsch are accepted too.

Can I send a number as text, like "1500"?

Yes. Text that is a plain number is read as a number. Text with thousands separators, a decimal comma or a unit is refused.

Why did my postal code lose its leading zero?

In a GET call, values are read as numbers where possible, so 01234 becomes 1234. Send the value with POST as a JSON string, "01234", to a String input.

Why does my output have many decimals?

The API returns the stored value of the cell, not the rounded display. Use ROUND in the workbook, or round with the output's formatString when you display the value.

Can an input be a list or a table?

No. An input is a single value in a single cell. Use several inputs, or keep the table in the workbook and select from it with an input and a lookup formula.

What is returned for an empty cell?

null. In a range output, each empty cell of the range is null.

How do I change the type of an input?

Hover over the input in the panel, click the pencil and choose another Data Type. Click Update Parameter, then save and publish again.

As an agent, should I send numbers as strings or numbers?

Send JSON numbers with POST: "rate": 0.05. Numeric strings are accepted too, but only plain ones with a point as the decimal separator.