FRQ QR Code API Documentation

Last Updated: 22-06-2025

Welcome to the FRQ QR Code API! This powerful API allows you to seamlessly integrate QR code generation into your applications, websites, and workflows. Create diverse QR codes, from simple URLs to complex vCards and WiFi configurations, with extensive customization options.

1. Introduction

Our API is designed to be RESTful, accepting JSON-formatted request bodies and returning JSON responses. Successful requests are indicated by standard HTTP success codes (200 OK, 201 Created), while errors are communicated with appropriate HTTP status codes and a JSON body detailing the issue.

Base URL:
All API endpoints are prefixed with:
https://frqtools.com/wp-json/frq-qr-api/v1/

2. Authentication

All requests to the FRQ QR Code API must be authenticated using a unique API Key. This key links your requests to your account and credit balance.

Obtaining Your API Key:

  1. Ensure you have an account on frqtools.com.
  2. Purchase an API Credit Pack from our API Credits page.
  3. Upon successful purchase, your API Key will be generated and emailed to you. You can also manage your key and view its prefix on your API Dashboard.

Using Your API Key:
Include your API Key in the HTTP request headers. The primary recommended header is:

  • Header Name: X-FRQ-API-KEY
  • Header Value: YOUR_API_KEY_HERE (e.g., frq_pk_xxxxxxxxxxxxxxxxxxxxxxxx)

Alternatively, you can use the standard Authorization header:

  • Header Name: Authorization
  • Header Value: Bearer YOUR_API_KEY_HERE

Security Note: Your API Key is sensitive. Treat it like a password. Do not expose it in client-side JavaScript or public repositories.

3. Credit System

  • Consumption: Each successful API call to generate a QR code (either static or dynamic) consumes one (1) credit.
  • Balance: View your current credit balance on your API Dashboard.
  • Replenishing: Purchase additional credit packs from our API Credits page.
  • Exhaustion: If your credits run out, API requests will fail with an HTTP 402 Payment Required status and an error code rest_api_credits_exhausted.

4. API Endpoints

4.1 Generate Static QR Code

Creates a static QR code image. The encoded data is fixed and cannot be changed after generation. The API returns a base64 encoded PNG image.

Endpoint: POST /generate-static

Request Body (JSON): See Request Payloads and Styling Options sections for details.

Example: Static URL QR Code

cURL:


curl -X POST \
  https://frqtools.com/wp-json/frq-qr-api/v1/generate-static \
  -H "X-FRQ-API-KEY: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_type": "url",
    "qr_data": {
        "url": "https://frqtools.com"
    },
    "styling_options": {
        "size": 300,
        "fg_color": "#1D3557",
        "bg_color": "#F1FAEE",
        "pattern_style": "rounded"
    }
}'

PHP (cURL):

Python (requests):


import requests
import json
import base64

api_key = 'YOUR_API_KEY_HERE'
api_url = 'https://frqtools.com/wp-json/frq-qr-api/v1/generate-static'
payload = {
    "qr_type": "url",
    "qr_data": {"url": "https://frqtools.com/python-static-example"},
    "styling_options": {"size": 300, "fg_color": "#457B9D"}
}
headers = {'Content-Type': 'application/json', 'X-FRQ-API-KEY': api_key}

response = requests.post(api_url, headers=headers, json=payload)
print(f"Status Code: {response.status_code}")
response_data = response.json()
print(json.dumps(response_data, indent=2))

# if response.ok and response_data.get('image_base64'):
#     img_data = base64.b64decode(response_data['image_base64'].split(',')[1])
#     with open('static_qr.png', 'wb') as f:
#         f.write(img_data)
#     print("Image saved as static_qr.png")

Successful Response (200 OK):


{
    "message": "Static QR code generated successfully.",
    "qr_type": "url",
    "qr_data_encoded": "https://frqtools.com",
    "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "styling_applied": {
        "fg_color": "#1D3557",
        "bg_color": "#F1FAEE",
        "qr_size": 300,
        "error_correction": "M",
        "pattern_style": "rounded",
        "logo_choice": "none",
        "custom_logo_url": "",
        "logo_size_ratio": 0.25,
        "logo_margin": 8
    }
}

4.2 Generate Dynamic QR Code

Creates or updates a dynamic QR code. The actual QR image will encode a short tracking URL (scan_url) managed by frqtools.com. The target content (e.g., destination URL) can be updated later via your FRQ QR Code Generator dashboard. The API returns data including the scan_url and a qr_code_styling_object which can be used with client-side libraries like QRCodeStyling.js to render the QR image.

Note: The QR types vcard, wifi, and text are not permitted for new dynamic QR code creation via the API.

Endpoint: POST /generate-dynamic

Request Body (JSON): See Request Payloads and Styling Options sections for details.

Example: Dynamic URL QR Code

cURL:


curl -X POST \
  https://frqtools.com/wp-json/frq-qr-api/v1/generate-dynamic \
  -H "X-FRQ-API-KEY: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_name": "My Dynamic Promo Link",
    "qr_type": "url",
    "qr_data": {
        "url": "https://frqtools.com/promo"
    },
    "styling_options": {
        "size": 280,
        "fg_color": "#A8DADC",
        "bg_color": "#1D3557"
    }
}'

PHP (cURL):

Python (requests):


# ... (imports as before) ...
api_key = 'YOUR_API_KEY_HERE'
api_url = 'https://frqtools.com/wp-json/frq-qr-api/v1/generate-dynamic'
payload = {
    "qr_name": "Python Dynamic Test",
    "qr_type": "url",
    "qr_data": {"url": "https://frqtools.com/python-dynamic-example"},
    "styling_options": {"size": 290, "fg_color": "#457B9D", "logo_choice": "scan_me"}
}
# ... (headers and request call similar to static example) ...
headers = {'Content-Type': 'application/json', 'X-FRQ-API-KEY': api_key}
response = requests.post(api_url, headers=headers, json=payload)
print(f"Status Code: {response.status_code}")
print(json.dumps(response.json(), indent=2))

Successful Response (201 Created):


{
    "message": "Dynamic QR Code created successfully!",
    "qr_post_id": 123,
    "qr_name": "My Dynamic Promo Link",
    "qr_type": "url",
    "short_id": "xyz789",
    "scan_url": "https://frqtools.com/qr/xyz789/",
    "target_data_stored": {
        "url": "https://frqtools.com/promo"
    },
    "styling_stored": {
        "fg_color": "#A8DADC",
        "bg_color": "#1D3557",
        "qr_size": 280,
        "error_correction": "M",
        "pattern_style": "extra-rounded", // "dots" maps to "extra-rounded"
        "logo_choice": "none"
    },
    "qr_code_styling_object": {
        "width": 280,
        "height": 280,
        "data": "https://frqtools.com/qr/xyz789/",
        "dotsOptions": { "color": "#A8DADC", "type": "extra-rounded" },
        "backgroundOptions": { "color": "#1D3557" }
        // ... other QRCodeStyling.js options
    }
}

5. Supported QR Types & qr_data Structures

The structure of the qr_data object in your JSON payload depends on the qr_type you specify.

Type: url (Static & Dynamic)


{
    "qr_type": "url",
    "qr_data": {
        "url": "https://your-website-link.com"
    }
}
  • url (string, required): The full website URL.

Type: text (Static API Only)


{
    "qr_type": "text",
    "qr_data": {
        "text_content": "Your important message or data here."
    }
}
  • text_content (string, required): The plain text to encode.

Type: whatsapp (Static & Dynamic)


{
    "qr_type": "whatsapp",
    "qr_data": {
        "phone": "14155551234", 
        "message": "Hello from the API!",
        "country_code_explicit": "1",   // Optional for dynamic, helps precise storage
        "phone_number_explicit": "4155551234" // Optional for dynamic
    }
}
  • phone (string, required): Full international phone number. For static QRs, use format suitable for wa.me link (e.g., no leading ‘+’). For dynamic, provide as needed for storage.
  • message (string, optional): Pre-filled WhatsApp message.
  • country_code_explicit (string, optional): Primarily for dynamic QR storage if your system requires it.
  • phone_number_explicit (string, optional): Primarily for dynamic QR storage.

Type: email (Static & Dynamic)


{
    "qr_type": "email",
    "qr_data": {
        "address": "recipient@example.com",
        "subject": "API Inquiry",
        "body": "Hello,\n\nI am interested in your services."
    }
}
  • address (string, required)
  • subject (string, optional)
  • body (string, optional)

Type: sms (Static & Dynamic)


{
    "qr_type": "sms",
    "qr_data": {
        "number": "12025550105", // Typically without leading '+' for SMSTO link
        "message": "Check out this cool API!"
    }
}
  • number (string, required)
  • message (string, optional)

Type: vcard (Static API Only)


{
    "qr_type": "vcard",
    "qr_data": {
        "firstName": "John",
        "lastName": "Doe",
        "organization": "FRQ Tech",
        "title": "API Developer",
        "phone": "+1-555-0100",
        "email": "john.doe@frqtools.com",
        "website": "https://frqtools.com",
        "adr_street": "123 API Lane",
        "adr_city": "Dev Town",
        "adr_state": "CA",
        "adr_zip": "90210",
        "adr_country": "USA",
        "note": "Met at API World Conf."
    }
}
  • (List all supported vCard fields as per your API’s sanitize_api_target_data function)

Type: wifi (Static API Only)


{
    "qr_type": "wifi",
    "qr_data": {
        "ssid": "MySecureNet",
        "password": "P@$$wOrd! \\;", // Remember to backslash-escape special chars: \ ; , " :
        "encryption": "WPA", 
        "hidden": false
    }
}
  • ssid (string, required): Network name. Client must escape \ ; , " : with a backslash.
  • password (string, optional): Network password (client must escape).
  • encryption (string, required): "WPA", "WEP", or "nopass".
  • hidden (boolean, optional): true or false.

6. Styling Options (styling_options object)

The styling_options object is optional in API requests. If not provided, or if specific properties are omitted, defaults from your plugin settings will be used. Note that some options might behave differently for server-generated static images versus the client-rendered dynamic QR’s qr_code_styling_object.

  • size (integer): Approximate pixel size of the QR code (e.g., 300). For static QRs, this influences the internal ‘scale’ parameter. Min: 50, Max: 1000.
  • fg_color (string): Foreground/dot color in hex format (e.g., "#000000").
  • bg_color (string): Background color in hex format (e.g., "#FFFFFF"). For static QRs, can be the string "transparent" (case-insensitive).
  • error_correction (string): Error correction level. Allowed: "L", "M", "Q", "H". Default: “M”. (Recommended “H” if using a logo).
  • pattern_style (string): The style of the data modules.
    • "square": Classic square dots. (Default)
    • "rounded": Rounded dots.
    • "extra-rounded": More circular dots (often referred to as “dots” style).
  • logo_choice (string): Specifies a logo.
    • "none" (Default)
    • "scan_me" (Predefined “Scan Me” icon)
    • "scan_me_bordered" (Predefined bordered “Scan Me” icon)
    • "custom" (Use a custom logo provided via custom_logo_url)

    Note for Static QRs: If a logo is chosen (scan_me, scan_me_bordered, or custom with a valid custom_logo_url), the Error Correction Level will automatically be set to ‘H’. However, the current static API output does not visually merge the logo onto the generated image. The logo options are primarily for dynamic QRs where the qr_code_styling_object is used by a client-side library like QRCodeStyling.js to render the logo.

  • custom_logo_url (string): Required if logo_choice is "custom". Must be a base64 encoded PNG data URI (e.g., "data:image/png;base64,iVBORw0KGgo...").
  • logo_size_ratio (number): (Primarily for dynamic QRs) Ratio of logo size to QR size (0.05 to 0.5). Default: 0.25.
  • logo_margin (integer): (Primarily for dynamic QRs) Margin around the logo in pixels. Default: 8.

7. Error Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. Error details are provided in a JSON response body.

HTTP Status Error code (in JSON) Common Description
200 OK N/A (Success) Request successful (e.g., static QR generated, dynamic QR updated).
201 Created N/A (Success) Dynamic QR successfully created.
400 Bad Request e.g., invalid_url, rest_missing_callback_param, rest_invalid_param, rest_dynamic_type_disabled The request was malformed, such as missing required parameters, invalid data formats, or attempting an unsupported operation. Check the message in the response for specifics.
401 Unauthorized rest_api_key_missing, rest_api_key_invalid_format The API key was missing from the request or was not in the expected format.
402 Payment Required rest_api_credits_exhausted Your API credits have run out. Please purchase more credits.
403 Forbidden rest_api_key_invalid_prefix, rest_api_key_mismatch_hash, rest_api_key_inactive The provided API key is invalid, inactive, revoked, or does not have permission for the requested action.
500 Internal Server Error e.g., qr_library_missing_output, qr_generation_failed An unexpected error occurred on the server while processing your request. If this persists, please contact support.

8. Support

If you have any questions, encounter issues, or require assistance with integrating the FRQ QR Code API, please contact our support team at contact@frqtools.com or visit our Support Page.

OUR TOOLS