Refresh a table from an API

If your prices already live in another system that offers a JSON endpoint, point a data table at it. Formspring fetches the list on a schedule and keeps a stored copy for your forms.

Set it up

1. Go to Forms → Data tables → New data table.
2. Choose API as the source.
3. Fill in:
   • API address - must start with https:// and be reachable on the public internet.
   • Access key name and value (optional) - for example Authorization and Bearer your-secret, or X-Api-Key. The value is stored encrypted and is never shown again. Leave the value blank when you edit later to keep the saved one.
   • Where the list is (optional) - the path to the list inside the response, such as data.rates. Leave it blank if the response is the list itself.
   • Refresh - every hour, every day, or only when you press Refresh now.
4. Save. The first fetch starts right away.

* * *

What the endpoint should return

JSON: a list of records, each one a row.

{
  "data": {
    "rates": [
      { "zone": "North", "max_kg": 500, "price": "90.00" },
      { "zone": "South", "max_kg": 100, "price": 40 }
    ]
  }
}

With Where the list is set to data.rates, this becomes a table with the columns zone, max_kg, and price.

• Numbers and number-like text become numbers; text with a leading zero stays text.
• Nested objects become columns named with dots, such as meta.days. True and false become the text true and false.
• Lists of simple values are joined with commas. Anything deeper is left out.
• A column that only some records have is filled blank for the others.

* * *

Rules for the fetch

• HTTPS only, and only public addresses. Local and private addresses are refused, including after redirects.
• The access key is sent to your address only, never to a redirect target.
• Up to 10 seconds per request, 3 redirects, and a 1 MB response.
• Up to 5,000 records and 20 columns.

* * *

When something goes wrong

If a refresh fails, the previous copy stays in place and forms keep working with it. The table page shows the reason (for example "The data source answered with an error (401)") and when the last successful refresh happened. Fix the cause and press Refresh now.

* * *

Good to know

• Each workspace can link up to 10 tables to an API.
• A table that refreshes from an API is read-only for pushes: sending rows with the push API answers 409, so two writers never fight over the same table. To switch to pushing, change the table's source back to a CSV file in the dashboard first (that needs a file upload).
• If you would rather send the data from your own system than have Formspring fetch it, use the push API.