List submissions

1. Request a page

Create a read key in the form Settings and store it as QUBEFORMS_READ_KEY on your server. GET /v1/read/submissions returns records for that key's form, newest first. A successful response is HTTP 200 with a JSON object whose data property is an array. An empty result is {"data":[]}.

curl --fail-with-body --get \
  'https://api.qubeforms.io/v1/read/submissions' \
  --header "Authorization: Bearer ${QUBEFORMS_READ_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'status=inbox' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'offset=0'

2. Filter and paginate

status defaults to inbox and accepts inbox, spam, archived, or deleted. Deleted records can appear in the list until purged, but their detail endpoint returns 404. limit defaults to 50 and is clamped to 1–250. offset defaults to 0 and is clamped to zero or greater. Increase offset by your page size until a page contains fewer records than requested. There is no total count or next-page token. New submissions and status changes can shift pages; use submission_id to avoid processing a record twice.

3. Search submissions

Add a URL-encoded search parameter to search within the selected status. Search matches the first recognized token in your query, ignoring letter case. It is a whole-token lookup, not phrase or substring search; use a complete word or email address. Searchable tokens contain 2–64 letters, numbers, or @ . _ - characters. A query with no recognized token returns no matches.

curl --fail-with-body --get \
  'https://api.qubeforms.io/v1/read/submissions' \
  --header "Authorization: Bearer ${QUBEFORMS_READ_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'status=inbox' \
  --data-urlencode 'search=alex@example.com'

4. Read the submitted fields

List records contain metadata such as submission_id, form_id, status, created_at, and trust_passport. They do not contain submitted field values. Use each submission_id with GET /v1/read/submissions/{submissionId} to retrieve those fields and attachment information. Successful read responses include Cache-Control: no-store; keep submission data out of shared caches.

5. Handle errors

HTTP 401 means the read key is missing, invalid, or revoked. HTTP 422 means the status filter is invalid. HTTP 500 means the service could not process the request. Error responses include ok: false and an error.message. Check the HTTP status before treating data as a result array.

6. Build a reliable export or polling job

Read pages on your server and fetch detail for each ID when you need field data. Store processed IDs to avoid repeats, and re-scan with overlap because offset pagination is not a fixed snapshot. Polling only Inbox misses messages later moved to Spam or Archived. Treat a detail 404 between list and fetch as a possible status change or cleanup, not necessarily a failed authentication. Export attachments separately before their retention deadline. Test empty results, multiple pages, and records changing status.

• Get a submission
• Export and retention