API Documentation

Introduction

Welcome to our API documentation. This API allows you to interact with our service programmatically, providing access to forms, responses, and other data within your SnapForm account.

Whether you are integrating SnapForm into your application or building custom workflows, our comprehensive API has you covered.

Authentication

All API requests require authentication using a JWT token. Include your token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

You can obtain a token by using the /api/auth/login endpoint with valid credentials.

Base URL

All API requests should be made to:

https://api.snapform.com/v1

Endpoints

Authentication

POST/api/auth/login

Authenticate a user and receive a JWT token.

Request Body

Field	Type	Required	Description
email	string	Yes	User email address
password	string	Yes	User password

Example Request

fetch('https://api.snapform.com/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'password123'
  })
})

Example Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_123",
    "name": "John Doe",
    "email": "[email protected]"
  }
}

POST/api/auth/register

Request Body

Field	Type	Required	Description
name	string	Yes	User full name
email	string	Yes	User email address
password	string	Yes	User password (min 8 characters)

Forms

GET/api/forms

List all forms for the authenticated user.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 10, max: 100)

Example Response

{
  "success": true,
  "data": [
    {
      "id": "form_123",
      "title": "Customer Feedback",
      "description": "Form for collecting customer feedback",
      "created_at": "2023-05-15T14:30:00Z",
      "response_count": 42
    },
    {
      "id": "form_456",
      "title": "Event Registration",
      "description": "Registration form for company event",
      "created_at": "2023-06-22T09:15:00Z",
      "response_count": 128
    }
  ],
  "meta": {
    "pagination": {
      "total": 15,
      "page": 1,
      "limit": 10,
      "pages": 2
    }
  }
}

GET/api/forms/:id

Get a specific form by ID.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Form ID

Error Handling

When an error occurs, the API returns an appropriate HTTP status code and error message.

Status Code	Description
400	Bad Request - The request was invalid
401	Unauthorized - Authentication is required or failed
403	Forbidden - You do not have permission to access this resource
404	Not Found - The requested resource does not exist
500	Internal Server Error - Something went wrong on the server

Error Response Format

{
  "success": false,
  "error": {
    "message": "Invalid credentials",
    "code": "auth_failed"
  }
}

Rate Limiting

API requests are limited to 100 requests per minute per user. When the rate limit is exceeded, a 429 (Too Many Requests) status code is returned.

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1626312000