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
  • 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://formrobin.com/api/v1/  

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

Authentication Overview

The FormRobin API uses Bearer token authentication. To get started, create a Personal Access Token in your account settings:

  1. Go to Settings > API
  2. Click Create New Token in the Personal Access Tokens section
  3. Include the token in the Authorization header of all API requests

FormRobin API Settings showing Personal Access Tokens section

See the API Authentication Guide for detailed instructions.

Quick Start Example

Step 1: Get Your Access Token

Request:

POST https://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://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",
      "url": "https://formrobin.com/f/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

Getting Current User Information

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

Request:

GET https://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://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,
      "completed_at": "2025-01-15T12:34:56Z",
      "form_field_responses": [
        {
          "id": 1,
          "form_session_id": "abc123",
          "form_field_id": "field1",
          "form_field_label": "Email",
          "value": "user@example.com"
        }
      ],
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "summer-promo",
      "utm_term": null,
      "utm_content": null,
      "referrer_url": "https://example.com",
      "landing_page_url": "https://formrobin.com/f/contact-form-abc123",
      "device_type": "desktop",
      "browser_name": "Chrome",
      "browser_version": "120.0",
      "operating_system": "Windows",
      "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
  • completed_at: Timestamp when the submission was completed
  • form_field_responses: Array of field responses with labels and values
  • utm_source, utm_medium, utm_campaign, utm_term, utm_content: UTM tracking parameters (Individual plan)
  • referrer_url: URL the visitor came from
  • landing_page_url: URL of the form page
  • device_type: Device category (desktop, mobile, tablet)
  • browser_name: Browser used for submission
  • browser_version: Browser version number
  • operating_system: Submitter's operating system
  • ip_address: Submitter's IP address
  • created_at: Record creation timestamp
  • updated_at: Record update timestamp

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

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.

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 Plan.

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.).


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

Related Articles