A
Atlas
...

Submissions API

Query and manage form submissions programmatically.

List Submissions

http
GET /api/v1/submissions

Returns submissions, newest first. With a project API key, you get that project's submissions. With an account token, you get submissions from all your projects. Submissions quarantined as spam are left out unless you pass include_spam=true.

Query Parameters

ParameterTypeDescription
formstringFilter by form slug
projectstringAccount tokens only: limit to one project ID
sinceISO 8601Only submissions after this date
untilISO 8601Only submissions before this date
limitintegerResults per page (default: 50, max: 100)
offsetintegerPagination offset
formatstringResponse format: json (default) or csv (up to 10,000 rows, ignores limit and offset)
include_spambooleantrue to include quarantined spam (default: false)

Example Request

bash
curl "https://atlasforms.app/api/v1/submissions?form=contact&limit=10" \
  -H "Authorization: Bearer fep_your_api_key"

Response

json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "form": "contact",
      "form_name": "Contact Form",
      "data": {
        "name": "John Doe",
        "email": "john@example.com",
        "message": "Hello!"
      },
      "metadata": {
        "ip": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "referrer": "https://example.com/contact",
        "submitted_from": "https://atlasforms.app/f/abc123xyz"
      },
      "webhook_status": "success",
      "is_spam": false,
      "spam_reason": null,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Response Fields

FieldDescription
idUnique submission ID
formForm slug
form_nameHuman-readable form name
dataThe submitted form data
metadata.ipSubmitter's IP address
metadata.user_agentBrowser/client user agent
metadata.referrerHTTP referrer
metadata.submitted_fromURL the submission was posted to
webhook_statuspending, success, or failed
is_spamtrue if the submission is quarantined as spam
spam_reasonWhy it is spam: ai_sales_pitch, ai_scam, ai_junk or ai_spam (AI spam filter), attack categories such as sqli or xss (attack-pattern detection), or manual (marked by you). null when is_spam is false
created_atISO 8601 timestamp

Get Single Submission

http
GET /api/v1/submissions/{id}

Returns a single submission with its file metadata. This endpoint requires a project API key (fep_...).

Example Request

bash
curl "https://atlasforms.app/api/v1/submissions/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer fep_your_api_key"

Response

json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "form": "contact",
    "form_name": "Contact Form",
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "Hello!"
    },
    "files": [
      {
        "id": "file-uuid",
        "filename": "document.pdf",
        "mime_type": "application/pdf",
        "size_bytes": 102400,
        "category": "document"
      }
    ],
    "metadata": {
      "ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "referrer": "https://example.com/contact",
      "submitted_from": "https://atlasforms.app/f/abc123xyz"
    },
    "is_spam": false,
    "spam_reason": null,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

To download a file, call GET /api/v1/files/{id}. See Files API.


Delete a Submission

http
DELETE /api/v1/submissions/{id}

Deletes the submission and its uploaded files. Requires a project API key. This cannot be undone.

json
{
  "success": true,
  "deleted_id": "550e8400-e29b-41d4-a716-446655440000",
  "files_deleted": 1
}

Export Submissions (CSV)

http
GET /api/v1/submissions?format=csv

Returns submissions as a CSV file for import into spreadsheets.

Example Request

bash
curl "https://atlasforms.app/api/v1/submissions?format=csv&form=contact" \
  -H "Authorization: Bearer fep_your_api_key" \
  -o submissions.csv

Response

csv
id,form,created_at,name,email,message
550e8400...,contact,2024-01-15T10:30:00Z,John Doe,john@example.com,Hello!

Date Filtering

Use since and until to filter by date range:

bash
# Submissions from the last 7 days
curl "https://atlasforms.app/api/v1/submissions?since=2024-01-08T00:00:00Z" \
  -H "Authorization: Bearer fep_your_api_key"

# Submissions in January 2024
curl "https://atlasforms.app/api/v1/submissions?since=2024-01-01&until=2024-01-31" \
  -H "Authorization: Bearer fep_your_api_key"

Pagination

Use limit and offset to paginate through results:

bash
# First page (submissions 1-50)
curl "https://atlasforms.app/api/v1/submissions?limit=50&offset=0" \
  -H "Authorization: Bearer fep_your_api_key"

# Second page (submissions 51-100)
curl "https://atlasforms.app/api/v1/submissions?limit=50&offset=50" \
  -H "Authorization: Bearer fep_your_api_key"

Check pagination.has_more to know if more results exist.


Error Responses

401 Unauthorized

json
{ "error": "Invalid API key" }

404 Not Found

json
{ "error": "Submission not found" }

429 Rate Limited

json
{ "error": "Rate limit exceeded" }