Name: QR Code API: SVG QR codes for URLs, Wi-Fi and vCard
Brand: leadharbor
SKU: api-leadharbor-qr-code
Availability: InStock
Author: API Market

Mohammed Samaan

# QR Code API

## Overview

The QR Code API generates QR codes as self-contained SVG strings and returns them in a small JSON response. It has one endpoint that covers six content types, chosen with the `type` parameter: plain text, URLs, Wi-Fi logins, vCard contact cards, email addresses and phone numbers. For text, URLs, email addresses and phone numbers the content goes in `text`. For Wi-Fi the API builds the network payload from `ssid`, `password`, `security` and `hidden`, and for vCard it builds the contact card from `name`, `org`, `phone`, `email` and `url`, escaping special characters so a Wi-Fi password with `;` or `,` still scans correctly. Every type accepts the same styling options: error-correction level, quiet-zone border, and foreground and background colours.

It is built for developers adding QR codes to apps, tickets, invoices, packaging and print, for teams that print Wi-Fi access cards for offices, shops and venues, and for event and CRM tools that hand out contact cards. Each response holds the `svg` markup, ready to embed in HTML or save as an `.svg` file, the `modules` count (the width of the QR grid), the `error_correction` level used, the `payload_length` of the encoded content, the `type`, and a `meta` object that you can ignore. Content that is too long for the chosen error-correction level is refused with `400` and a message that says so.

## Features

*   **1 endpoint**: `GET /v1/market/qr` generates one QR code per call.
*   **6 content types**: `text` (default), `url` (http or https only), `wifi`, `vcard`, `email` and `phone`.
*   **Correct payloads**: Wi-Fi and vCard fields are escaped, so passwords and names with special characters scan correctly.
*   **SVG output**: A self-contained SVG string that scales to any size without losing sharpness.
*   **Styling options**: Error correction `L`, `M`, `Q` or `H`, a quiet-zone border of 0 to 10 modules, and hex foreground and background colours.
*   **Method**: Codes are generated on the server from the query parameters. No image upload is needed.
*   **Clear errors**: An invalid field, or content that does not fit, returns `400` with a message that names the field.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Links on print**: Put a scannable link to a product page, menu or review form on flyers, packaging and receipts.
*   **Guest Wi-Fi cards**: Generate a code that joins guests to a network without typing the password.
*   **Contact sharing**: Add a vCard QR code to business cards, email signatures and event badges.
*   **Tickets and invoices**: Embed a code that carries a booking reference or payment link in generated PDFs and emails.
*   **Branded codes**: Match the code to your brand colours and pick a higher error-correction level for codes printed small or on rough surfaces.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/leadharbor/qr-code
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Generate QR code

Generates a QR code for the given content and returns it as an SVG string, with the grid size, error-correction level, payload length and type.

**Method:** `GET`

**Endpoint:** `/v1/market/qr`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `type` | query | Content type: `text`, `url`, `wifi`, `vcard`, `email` or `phone`. | string | No | `text` | - |
| `text` | query | The content for types `text`, `url`, `email` and `phone`: the text, the full URL (http or https), the email address or the phone number. Without it these types answer `400` with `text: required.` | string | Yes, for `text`, `url`, `email` and `phone` | - | Depends on `ecc` |
| `ssid` | query | `wifi`: network name. | string | No | - | - |
| `password` | query | `wifi`: network password. | string | No | - | - |
| `security` | query | `wifi`: `WPA`, `WEP` or `nopass`. | string | No | - | - |
| `hidden` | query | `wifi`: `true` for a hidden network. | string | No | - | - |
| `name` | query | `vcard`: full name. | string | No | - | - |
| `org` | query | `vcard`: organisation. | string | No | - | - |
| `phone` | query | `vcard`: phone number. For `type=phone`, send the number in `text` instead. | string | No | - | - |
| `email` | query | `vcard`: email address. For `type=email`, send the address in `text` instead. | string | No | - | - |
| `url` | query | `vcard`: website. For `type=url`, send the URL in `text` instead. | string | No | - | - |
| `ecc` | query | Error-correction level: `L`, `M`, `Q` or `H`. Higher levels survive more damage but hold less content. | string | No | `M` | - |
| `border` | query | Quiet-zone width in modules. | integer | No | `4` | 10 |
| `foreground` | query | Hex colour of the modules, without `#`, for example `1a1a2e`. | string | No | `000000` | - |
| `background` | query | Hex colour of the background, without `#`. | string | No | `ffffff` | - |

The `url`, `email` and `phone` parameters are only used to build a vCard. For `type=url`, `type=email` and `type=phone` they are ignored, and the content must go in `text`.

**Example Request (URL):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/qr-code/v1/market/qr?type=url&text=https%3A%2F%2Fapi.market" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 330 330\"><rect fill=\"#ffffff\" width=\"330\" height=\"330\"/><path fill=\"#000000\" d=\"M40,40h10v10h-10z ... M280,280h10v10h-10z\"/></svg>",
  "modules": 27,
  "error_correction": "M",
  "payload_length": 18,
  "type": "url",
  "meta": {
    "user": null
  }
}
```

The `svg` string is shortened here. The real value is the complete SVG markup, about 6 KB for a short URL.

**Example Request (Wi-Fi):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/qr-code/v1/market/qr?type=wifi&ssid=Office&password=secret&security=WPA" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 370 370\"><rect fill=\"#ffffff\" width=\"370\" height=\"370\"/><path fill=\"#000000\" d=\"M40,40h10v10h-10z ... M290,320h10v10h-10z\"/></svg>",
  "modules": 31,
  "error_correction": "M",
  "payload_length": 30,
  "type": "wifi",
  "meta": {
    "user": null
  }
}
```

**Example Request (vCard):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/qr-code/v1/market/qr?type=vcard&name=Ada%20Lovelace&org=Analytical%20Engines&phone=%2B441234567890&email=ada%40example.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

The response has the same fields as the other types, with `type` set to `vcard`. A contact card holds more data than a short URL, so the grid is larger and the SVG string is about 20 KB.

**Example Request (plain text):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/qr-code/v1/market/qr?type=text&text=Hello%20from%20API.market" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 330 330\"><rect fill=\"#ffffff\" width=\"330\" height=\"330\"/><path fill=\"#000000\" d=\"M40,40h10v10h-10z ... M280,280h10v10h-10z\"/></svg>",
  "modules": 27,
  "error_correction": "M",
  "payload_length": 21,
  "type": "text",
  "meta": {
    "user": null
  }
}
```

**Example Request (email):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/qr-code/v1/market/qr?type=email&text=ada%40example.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 330 330\"><rect fill=\"#ffffff\" width=\"330\" height=\"330\"/><path fill=\"#000000\" d=\"M40,40h10v10h-10z ... M280,280h10v10h-10z\"/></svg>",
  "modules": 27,
  "error_correction": "M",
  "payload_length": 22,
  "type": "email",
  "meta": {
    "user": null
  }
}
```

**Example Request (phone):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/qr-code/v1/market/qr?type=phone&text=%2B441234567890" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 330 330\"><rect fill=\"#ffffff\" width=\"330\" height=\"330\"/><path fill=\"#000000\" d=\"M40,40h10v10h-10z ... M280,280h10v10h-10z\"/></svg>",
  "modules": 27,
  "error_correction": "M",
  "payload_length": 17,
  "type": "phone",
  "meta": {
    "user": null
  }
}
```

**Example Request (custom colours, border and error correction):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/qr-code/v1/market/qr?text=https%3A%2F%2Fapi.market&ecc=H&border=2&foreground=1a1a2e&background=ffffff" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 330 330\"><rect fill=\"#ffffff\" width=\"330\" height=\"330\"/><path fill=\"#1a1a2e\" d=\"M20,20h10v10h-10z ... M280,300h10v10h-10z\"/></svg>",
  "modules": 31,
  "error_correction": "H",
  "payload_length": 18,
  "type": "text",
  "meta": {
    "user": null
  }
}
```

With no `type`, the content is encoded as plain text. Error correction `H` needs a larger grid for the same content, 31 modules here against 27 at the default `M`.

**Response fields:**

| Field | Description |
|---|---|
| `svg` | The QR code as a complete, self-contained SVG string. |
| `modules` | The number of modules (cells) along each side of the QR grid. |
| `error_correction` | The error-correction level used: `L`, `M`, `Q` or `H`. |
| `payload_length` | The length of the content encoded in the code. |
| `type` | The content type used. |
| `meta` | Metadata (`user` is `null`). You can ignore it. |

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The QR code was generated and the SVG is in `svg`. |
| 400 | Bad Request | A field is invalid or missing, for example no `text` for a `url`, `email` or `phone` code, a URL that is not http or https, or content too long for the chosen `ecc` level. The message names the field. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The request path is wrong. Use `/v1/market/qr`. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while generating the code. Retry after a short delay. |

## Rate Limits

The Free trial, Starter and PAYG plans each allow 10 requests per second. The Free trial includes 500 calls with a hard limit, Starter includes 10,000 calls and bills extra calls at $0.001 each, and PAYG has no subscription and is billed at $0.001 per call. Requests above the per-second limit, or after the Free trial's 500 calls are used up, return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header, which says how many seconds to wait. In our tests a Wi-Fi code took about 0.55 seconds and a vCard about 0.7 seconds.

## FAQ

**How do I make a QR code for a URL, email address or phone number?**

Set `type` to `url`, `email` or `phone` and put the content in `text`, for example `type=url&text=https://example.com`. The separate `url`, `email` and `phone` parameters are only for vCards, and a request without `text` returns `400` with `text: required.`

**What format is the QR code returned in?**

JSON with an `svg` field that holds the complete SVG markup. You can place it directly in an HTML page, save it as an `.svg` file, or convert it to PNG on your side. The API does not return PNG.

**Which error-correction level should I use?**

`M` is the default and suits most screens and clean prints. Use `Q` or `H` when the code may be printed small, scuffed or partly covered by a logo. Higher levels make the grid larger for the same content and reduce how much content fits.

**Why did I get a 400 saying the content does not fit?**

Each error-correction level has a maximum payload. Shorten the content, or lower `ecc` to `L` or `M` to fit more.

**Will a Wi-Fi password with special characters work?**

Yes. Characters such as `;` and `,` are escaped in the Wi-Fi payload so the code scans correctly. URL-encode the password in the query string as you would any other parameter.

**How do I pass colours?**

Send six-digit hex values without `#`, such as `foreground=1a1a2e&background=ffffff`. Keep strong contrast between the two so scanners can read the code.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


QR code API that returns SVG QR codes for URLs, text, Wi-Fi logins, vCards, email and phone numbers, with error correction, border and colour options.

QR Code API: SVG QR codes for URLs, Wi-Fi and vCard

Free trial