FormRobin API: Getting Started

Access your forms programmatically with the FormRobin REST API - automate form creation, management, and data retrieval.

What Is the FormRobin API?

The FormRobin API is a RESTful API that allows you to:

• Create, read, update, and delete forms programmatically
• Retrieve form responses and submission data
• Manage folders and organization
• Get authenticated user information
• Integrate FormRobin into your applications and workflows
• Automate form management tasks

Plan Requirement: The API is available on all FormRobin plans (Free and Individual).

API Base URL

All API requests are made to:

https://forms.formrobin.com/api/v1/

All requests must be made over HTTPS. HTTP requests will fail.

Authentication Overview

The FormRobin API uses Bearer token authentication with JWT (JSON Web Tokens). To use the API:

1. Obtain an access token by sending your credentials to the login endpoint
2. Include the token in the Authorization header of all subsequent requests
3. Tokens expire after a period of time and must be refreshed

See the API Authentication Guide for detailed instructions.

Quick Start Example

Step 1: Get Your Access Token

Request:

POST https://forms.formrobin.com/api/jwt/login

Body (JSON):

{
  "email": "your-email@example.com",
  "password": "your-password"
}

Response:

{
  "access": "your-jwt-token-here",
  "token_type": "bearer",
  "expires_in": 31536000
}

Step 2: Make an API Request

Request:

GET https://forms.formrobin.com/api/v1/forms

Headers:

Authorization: Bearer your-jwt-token-here
Content-Type: application/json
Accept: application/json

Response:

{
  "data": [
    {
      "id": 123,
      "name": "Contact Form",
      "slug": "contact-form-abc123",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Available API Endpoints

User Endpoints

• GET /api/v1/me - Get current authenticated user information

Form Endpoints

• GET /api/v1/forms - List all forms (paginated, 100 per page)
• POST /api/v1/forms - Create a new form
• GET /api/v1/forms/{id} - Get a specific form
• PUT /api/v1/forms/{id} - Update a form
• DELETE /api/v1/forms/{id} - Delete a form
• GET /api/v1/forms/{id}/sessions - Get form submissions/responses

Folder Endpoints

• GET /api/v1/folders - List all folders
• POST /api/v1/folders - Create a new folder
• GET /api/v1/folders/{id} - Get a specific folder
• PUT /api/v1/folders/{id} - Update a folder
• DELETE /api/v1/folders/{id} - Delete a folder

Getting Current User Information

Use the /api/v1/me  endpoint to retrieve information about the authenticated user.

Request:

GET https://forms.formrobin.com/api/v1/me

Headers:

Authorization: Bearer your-jwt-token-here
Content-Type: application/json

Response:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Use Cases:

• Verify authentication is working correctly
• Display user information in your application
• Confirm which account you're authenticated as

Getting Form Submissions

Retrieve all submissions for a specific form using the /api/v1/forms/{id}/sessions  endpoint.

Request:

GET https://forms.formrobin.com/api/v1/forms/123/sessions

Headers:

Authorization: Bearer your-jwt-token-here
Content-Type: application/json
Accept: application/json

Response Example:

{
  "data": [
    {
      "id": "abc123",
      "form_id": 123,
      "user_id": 42,
      "completed_at": "2025-01-15T12:34:56Z",
      "form_field_responses": [
        {
          "form_field_id": "field1",
          "label": "Email",
          "value": "user@example.com"
        }
      ],
      "utm_source": "google",
      "utm_medium": "cpc",
      "referrer_url": "https://example.com",
      "device_type": "desktop",
      "browser_name": "Chrome",
      "ip_address": "192.168.1.1",
      "created_at": "2025-01-15T12:34:56Z",
      "updated_at": "2025-01-15T12:34:56Z"
    }
  ]
}

Form Session Field Descriptions

• id: Unique submission identifier
• form_id: ID of the form that was submitted
• user_id: ID of the logged-in user who submitted the form (null if submitted by anonymous visitor)
• completed_at: Timestamp when the submission was completed
• form_field_responses: Array of field responses with labels and values
• utm_source, utm_medium, etc.: UTM tracking parameters (Individual plan)
• referrer_url: URL the visitor came from
• device_type: Device category (desktop, mobile, tablet)
• browser_name: Browser used for submission
• ip_address: Submitter's IP address
• created_at: Record creation timestamp
• updated_at: Record update timestamp

💡 Note: The user_id  field is useful for multi-user accounts to track which team member submitted a form. For public submissions by anonymous visitors, this field will be null.

Common Request Headers

Include these headers in all API requests:

• Authorization: Bearer your-jwt-token  (required for all endpoints except login)
• Content-Type: application/json  (required for POST/PUT requests)
• Accept: application/json  (recommended)

Response Format

All API responses are in JSON format.

Successful Response

Most successful GET requests return data in this format:

{
  "data": [
    // array of objects or single object
  ]
}

Error Response

Error responses include HTTP status codes and error details:

{
  "message": "Error description",
  "errors": {
    "field_name": ["Error detail"]
  }
}

HTTP Status Codes

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required or token invalid
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 422 Unprocessable Entity - Validation errors
• 500 Internal Server Error - Server error

Pagination

List endpoints (e.g., /api/v1/forms ) return paginated results:

• Default page size: 100 items
• Page parameter: Add ?page=2  to get subsequent pages
• Response includes pagination metadata

Rate Limiting

The FormRobin API has rate limits to ensure fair usage:

• Limits apply per user account
• Excessive requests may be throttled
• Respect 429 (Too Many Requests) responses
• Implement exponential backoff for retries

Full API Documentation

Complete API documentation is available at:

https://forms.formrobin.com/openapi

This OpenAPI specification includes:

• All available endpoints
• Request/response schemas
• Field descriptions and validation rules
• Example requests and responses

Next Steps

1. Read the API Authentication Guide
2. Learn how to Create Forms via API
3. Explore the full OpenAPI documentation
4. Set up webhooks for real-time data (Individual tier)

Common API Workflows

Creating a Form and Retrieving Responses

1. Authenticate and get access token
2. POST to /api/v1/forms  to create a form
3. Share the form URL with users
4. GET /api/v1/forms/{id}/sessions  to retrieve responses
5. Process the response data in your application

Managing Forms Programmatically

1. GET /api/v1/me  to verify authentication
2. GET /api/v1/forms  to list all forms
3. POST /api/v1/folders  to create organization folders
4. PUT /api/v1/forms/{id}  to update form settings
5. DELETE /api/v1/forms/{id}  to remove old forms

Tracking User Submissions

1. GET /api/v1/forms/{id}/sessions  to retrieve all submissions
2. Check the user_id  field in each session to identify logged-in submitters
3. Cross-reference with /api/v1/me  or user records
4. Filter submissions by user or track team member activity

API Troubleshooting

Issue: 401 Unauthorized error

Fix: Verify your access token is valid and included in the Authorization header as Bearer your-token . Tokens may expire - obtain a new token via /api/jwt/login .

Issue: 422 Validation error

Fix: Check the error response for specific field validation errors. Ensure all required fields are provided and in the correct format.

Issue: CORS errors in browser

Fix: The API is designed for server-side use, not browser JavaScript. Use a backend proxy or server-side language (Node.js, Python, PHP) to make API calls.

Issue: user_id is always null in responses

Fix: The user_id field is only populated when a logged-in FormRobin user submits a form. Public submissions by anonymous visitors will have user_id set to null. This is expected behavior.

FAQ

Q: Is the API available on the Free Plan?

A: Yes! The API is available on all plans including the Free Plan.

Q: How long do access tokens last?

A: Tokens expire after approximately 1 year (31,536,000 seconds). Check the expires_in  value in the login response.

Q: Can I use the API from the browser?

A: The API is designed for server-side use. Browser requests may encounter CORS restrictions. Use a backend server to make API calls.

Q: What's the difference between the API and webhooks?

A: The API allows you to pull data from FormRobin (you make requests). Webhooks push data to you in real-time (FormRobin makes requests to your endpoint). Webhooks require Individual tier.

Q: Are there client libraries for the API?

A: Not officially. Use any HTTP client library in your language of choice (curl, axios, requests, Guzzle, etc.).

Q: What does the user_id field represent in form sessions?

A: The user_id indicates which logged-in FormRobin account holder submitted the form. It's null for public/anonymous submissions. This is useful for tracking activity in multi-user or team accounts.

Need help with the API? Contact our support team - we're here to help!