REST API

A REST API (Representational State Transfer Application Programming Interface) is a standardized interface that allows systems to communicate over HTTP by adhering to REST principles. It uses stateless operations and standard HTTP methods like GET, POST, PUT, and DELETE to perform CRUD (Create, Read, Update, Delete) operations on resources, typically represented in JSON or XML formats.

You can use the REST API with any backend, framework, or library. If we don't provide a specific example for your stack, simply use your favorite HTTP client or library to make POST requests to the Basestack Forms endpoint.

Prerequisites

Before you begin, make sure you have:

A Basestack Forms account
Any library, framework, or language that supports HTTP calls

Quick Setup Guide

The Basestack Forms REST API accepts standard HTTP POST requests. Follow these steps to get started:

Understand the endpoint format

Your Basestack Forms endpoint follows this format:

https://forms-api.basestack.co/v1/s/[KEY]?mode=rest

Replace [KEY] with your form's unique key from the Basestack Forms Dashboard.

Make sure to include mode=rest in the query string to receive JSON responses instead of HTML redirects.

Test with cURL

Use the cURL command below to test your endpoint. This example demonstrates the required headers and request format.

curl.sh

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name": "John Doe", "message": "Hello World"}' \
"https://forms-api.basestack.co/v1/s/[KEY]?mode=rest"

Attaching files

File uploads must be enabled in Settings → General first (off by default on new forms). To send files, switch the request body from JSON (-d '{...}') to multipart form data (-F "name=value" per field). cURL sets the multipart/form-data Content-Type (with boundary) for you, so omit the explicit -H "Content-Type: ..." header.

Each file must be 1 MB or smaller, and a single submission may include at most 5 files. The server returns HTTP 413 if either limit is exceeded. See File Uploads → for full details.

Simple example: single file

Use -F "fieldname=@/path/to/file" to attach a file. The @ prefix tells cURL to read the file from disk.

single-file.sh

curl -X POST \
  -H "Accept: application/json" \
  -F "name=John Doe" \
  -F "[email protected]" \
  -F "message=Resume attached." \
  -F "resume=@/path/to/resume.pdf" \
  "https://forms-api.basestack.co/v1/s/[KEY]?mode=rest"

Complex example: multiple files

Repeat the same field name to send several files under one key (the same way <input type="file" multiple> behaves in HTML). You can also mix several distinct file fields in the same request.

multi-file.sh

curl -X POST \
  -H "Accept: application/json" \
  -F "full_name=Ada Lovelace" \
  -F "[email protected]" \
  -F "role=Senior Engineer" \
  -F "cv=@/path/to/cv.pdf" \
  -F "portfolio=@/path/to/case-study-1.pdf" \
  -F "portfolio=@/path/to/case-study-2.pdf" \
  -F "portfolio=@/path/to/cover.jpg" \
  "https://forms-api.basestack.co/v1/s/[KEY]?mode=rest"

Need to set the content type explicitly (for example when the file extension is missing or ambiguous)? Append ;type=image/png after the path: -F "photo=@./avatar;type=image/png".

Inspecting error responses

If a submission is rejected for size or count reasons, the server replies with HTTP 413 and a JSON body explaining what failed:

{
  "error": true,
  "code": 413,
  "message": "Error: File \"resume.pdf\" exceeds the 1.00MB upload limit",
  "url": "https://your-error-page/..."
}

Add -i to your cURL command to see the status line and headers while you're debugging.

REST API

On this page