Forms API

Create and manage custom forms for collecting data from your customers.

List Forms

GET /api/external/v1/forms

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 15, max: 100)
status	string	Filter: active, inactive
search	string	Search in name and description
sort_by	string	Sort field: created_at, name, is_active
sort_dir	string	Sort order: asc, desc

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/forms?status=active&sort_by=name&sort_dir=asc" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Player Feedback Survey",
      "description": "Help us improve the server",
      "success_message": "Thank you for your feedback!",
      "is_active": true,
      "require_login": false,
      "recaptcha_enabled": true,
      "opens_at": null,
      "closes_at": null,
      "submission_limit": null,
      "status_label": "Active",
      "schedule_info": null,
      "remaining_submissions": null,
      "submissions_count": 42,
      "fields_count": 5,
      "fields": [
        {
          "id": 1,
          "label": "Your Name",
          "name": "player_name",
          "type": "text",
          "placeholder": "Enter your in-game name",
          "options": null,
          "is_required": true,
          "sort_order": 0
        },
        {
          "id": 2,
          "label": "Email Address",
          "name": "email",
          "type": "email",
          "placeholder": "your@email.com",
          "options": null,
          "is_required": true,
          "sort_order": 1
        }
      ],
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 15,
    "total": 18
  }
}

Get Single Form

GET /api/external/v1/forms/{id}

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/forms/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Player Feedback Survey",
    "description": "Help us improve the server",
    "success_message": "Thank you for your feedback!",
    "is_active": true,
    "require_login": false,
    "recaptcha_enabled": true,
    "opens_at": null,
    "closes_at": "2025-02-28T23:59:59Z",
    "submission_limit": 100,
    "inherit_theme_styling": true,
    "styling": null,
    "status_label": "Active",
    "schedule_info": "Closes: Feb 28, 2025 11:59 PM",
    "remaining_submissions": 58,
    "submissions_count": 42,
    "fields": [
      {
        "id": 1,
        "label": "Your Name",
        "name": "player_name",
        "type": "text",
        "placeholder": "Enter your in-game name",
        "options": null,
        "is_required": true,
        "sort_order": 0
      },
      {
        "id": 2,
        "label": "Email Address",
        "name": "email",
        "type": "email",
        "placeholder": "your@email.com",
        "options": null,
        "is_required": true,
        "sort_order": 1
      },
      {
        "id": 3,
        "label": "How would you rate our server?",
        "name": "rating",
        "type": "select",
        "placeholder": null,
        "options": [
          { "value": "excellent", "label": "Excellent" },
          { "value": "good", "label": "Good" },
          { "value": "average", "label": "Average" },
          { "value": "poor", "label": "Poor" }
        ],
        "is_required": true,
        "sort_order": 2
      },
      {
        "id": 4,
        "label": "Additional Comments",
        "name": "comments",
        "type": "textarea",
        "placeholder": "Share your thoughts...",
        "options": null,
        "is_required": false,
        "sort_order": 3
      },
      {
        "id": 5,
        "label": "Subscribe to newsletter",
        "name": "subscribe",
        "type": "checkbox",
        "placeholder": null,
        "options": null,
        "is_required": false,
        "sort_order": 4
      }
    ],
    "fields_count": 5,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Create Form

POST /api/external/v1/forms

Request Body

Parameter	Type	Required	Description
name	string	Yes	Form name (max 255 chars)
description	string	No	Form description (max 1000 chars)
success_message	string	No	Message shown after submission (max 500 chars)
is_active	boolean	No	Whether form is active (default: true)
require_login	boolean	No	Require customer login to submit (default: false)
recaptcha_enabled	boolean	No	Enable reCAPTCHA protection (default: false)
opens_at	string	No	ISO 8601 date when form opens
closes_at	string	No	ISO 8601 date when form closes (must be after opens_at)
submission_limit	integer	No	Maximum number of submissions allowed
inherit_theme_styling	boolean	No	Use store theme styling (default: true)
styling	object	No	Custom styling options
fields	array	Yes	Array of form fields (min 1)

Field Object

Parameter	Type	Required	Description
label	string	Yes	Field label (max 255 chars)
name	string	Yes	Field name for data storage (max 50 chars, alphanumeric with underscores)
type	string	Yes	Field type: text, email, number, textarea, select, checkbox, radio, date
placeholder	string	No	Placeholder text (max 255 chars)
options	array	No	Options for select/radio/checkbox fields
is_required	boolean	No	Whether field is required (default: false)
sort_order	integer	No	Display order (default: 0)

Styling Object

Parameter	Type	Description
background_color	string	Hex color code (e.g., "#ffffff")
text_color	string	Hex color code
accent_color	string	Hex color code
button_color	string	Hex color code
button_text_color	string	Hex color code
button_text	string	Submit button text (max 50 chars)
border_radius	string	Border radius value (e.g., "8px")

Example Request

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/forms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Player Feedback Survey",
    "description": "Help us improve the server",
    "success_message": "Thank you for your feedback!",
    "is_active": true,
    "require_login": false,
    "recaptcha_enabled": true,
    "closes_at": "2025-02-28T23:59:59Z",
    "submission_limit": 100,
    "fields": [
      {
        "label": "Your Name",
        "name": "player_name",
        "type": "text",
        "placeholder": "Enter your in-game name",
        "is_required": true,
        "sort_order": 0
      },
      {
        "label": "Email Address",
        "name": "email",
        "type": "email",
        "placeholder": "your@email.com",
        "is_required": true,
        "sort_order": 1
      },
      {
        "label": "How would you rate our server?",
        "name": "rating",
        "type": "select",
        "options": [
          { "value": "excellent", "label": "Excellent" },
          { "value": "good", "label": "Good" },
          { "value": "average", "label": "Average" },
          { "value": "poor", "label": "Poor" }
        ],
        "is_required": true,
        "sort_order": 2
      }
    ]
  }'

Response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Player Feedback Survey",
    "description": "Help us improve the server",
    "success_message": "Thank you for your feedback!",
    "is_active": true,
    "require_login": false,
    "recaptcha_enabled": true,
    "opens_at": null,
    "closes_at": "2025-02-28T23:59:59Z",
    "submission_limit": 100,
    "status_label": "Active",
    "submissions_count": 0,
    "fields": [...],
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-20T14:30:00Z"
  },
  "message": "Form created successfully"
}

Update Form

PUT /api/external/v1/forms/{id}

Request Body

Same parameters as Create Form. All fields are optional - only include fields you want to update.

Example Request

curl -X PUT "https://yourstore.pixlpay.net/api/external/v1/forms/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Feedback Survey",
    "is_active": false,
    "submission_limit": 200
  }'

Response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Updated Feedback Survey",
    "is_active": false,
    "submission_limit": 200,
    ...
  },
  "message": "Form updated successfully"
}

Delete Form

DELETE /api/external/v1/forms/{id}

Example Request

curl -X DELETE "https://yourstore.pixlpay.net/api/external/v1/forms/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "message": "Form deleted successfully"
}

List Form Submissions

GET /api/external/v1/forms/{id}/submissions

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)
from	string	Start date (YYYY-MM-DD or ISO 8601)
to	string	End date (YYYY-MM-DD or ISO 8601)
search	string	Search in submission data
sort_by	string	Sort field: created_at
sort_dir	string	Sort order: asc, desc

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/forms/1/submissions?from=2025-01-01&per_page=50" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "submissions": {
      "data": [
        {
          "id": 1,
          "form_id": 1,
          "customer": {
            "id": 5,
            "email": "player@example.com",
            "name": "Player123"
          },
          "data": {
            "player_name": "CoolPlayer99",
            "email": "player@example.com",
            "rating": "excellent",
            "comments": "Great server!"
          },
          "formatted_data": {
            "Your Name": "CoolPlayer99",
            "Email Address": "player@example.com",
            "How would you rate our server?": "Excellent",
            "Additional Comments": "Great server!"
          },
          "ip_address": "192.168.1.1",
          "user_agent": "Mozilla/5.0...",
          "created_at": "2025-01-18T09:15:00Z"
        }
      ],
      "current_page": 1,
      "last_page": 3,
      "per_page": 20,
      "total": 42
    },
    "form": {
      "id": 1,
      "name": "Player Feedback Survey",
      "fields": [
        { "name": "player_name", "label": "Your Name", "type": "text" },
        { "name": "email", "label": "Email Address", "type": "email" },
        { "name": "rating", "label": "How would you rate our server?", "type": "select" },
        { "name": "comments", "label": "Additional Comments", "type": "textarea" }
      ]
    }
  }
}

Get Single Submission

GET /api/external/v1/forms/{form_id}/submissions/{submission_id}

Example Request

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/forms/1/submissions/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "data": {
    "submission": {
      "id": 1,
      "form_id": 1,
      "customer": {
        "id": 5,
        "email": "player@example.com",
        "name": "Player123"
      },
      "data": {
        "player_name": "CoolPlayer99",
        "email": "player@example.com",
        "rating": "excellent",
        "comments": "Great server!"
      },
      "formatted_data": {
        "Your Name": "CoolPlayer99",
        "Email Address": "player@example.com",
        "How would you rate our server?": "Excellent",
        "Additional Comments": "Great server!"
      },
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2025-01-18T09:15:00Z"
    }
  }
}

Delete Submission

DELETE /api/external/v1/forms/{form_id}/submissions/{submission_id}

Example Request

curl -X DELETE "https://yourstore.pixlpay.net/api/external/v1/forms/1/submissions/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "message": "Submission deleted successfully"
}

Form Object

Field	Type	Description
id	integer	Unique identifier
name	string	Form name
description	string	Form description
success_message	string	Message shown after submission
is_active	boolean	Whether form is active
require_login	boolean	Whether login is required
recaptcha_enabled	boolean	Whether reCAPTCHA is enabled
opens_at	string	ISO 8601 date when form opens
closes_at	string	ISO 8601 date when form closes
submission_limit	integer	Maximum submissions allowed (null = unlimited)
inherit_theme_styling	boolean	Whether to use store theme
styling	object	Custom styling options
status_label	string	Human-readable status: Active, Inactive, Scheduled, Closed, Full
schedule_info	string	Schedule display text
remaining_submissions	integer	Remaining submissions until limit (null = unlimited)
submissions_count	integer	Total number of submissions
fields	array	Form field definitions
fields_count	integer	Number of fields
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Form Field Object

Field	Type	Description
id	integer	Field identifier
label	string	Display label
name	string	Field name (used as key in submission data)
type	string	Field type: text, email, number, textarea, select, checkbox, radio, date
placeholder	string	Placeholder text
options	array	Options for select/radio/checkbox (each with value and label)
is_required	boolean	Whether field is required
sort_order	integer	Display order

Form Submission Object

Field	Type	Description
id	integer	Submission identifier
form_id	integer	Parent form ID
customer	object	Customer who submitted (if logged in)
data	object	Raw submission data (field names as keys)
formatted_data	object	Submission data with field labels as keys
ip_address	string	Submitter's IP address
user_agent	string	Submitter's browser user agent
created_at	string	ISO 8601 timestamp

Required Scopes

Endpoint	Required Scope
List forms	forms:read
Get form	forms:read
Create form	forms:write
Update form	forms:write
Delete form	forms:write
List submissions	forms:read
Get submission	forms:read
Delete submission	forms:write

Errors

Status	Error	Description
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Invalid or missing token
403	Forbidden	Token lacks required scope
404	Not Found	Form or submission doesn't exist
422	Unprocessable Entity	Validation failed