BizKitHub
DocsAPI ReferenceSupport/api/v1/support/contact-form
postSupportPublic API v1

/api/v1/support/contact-form

Creates a support ticket from a contact form submission. Includes anti-spam geolocation check. Optionally registers the customer as a contact. Accepts up to 5 optional file attachments via multipart/form-data which are uploaded to blob storage and linked to the ticket. When called through a trusted proxy (e.g. support.bizkithub.com), pass the end-user IP via ?customerRealIp=… so the geolocation resolves to the real reporter, not the proxy host.

supportpostApiV1SupportContact-form

Parameters

2 query · JSON body

Query parameters

· 2
apiKeystringRequired

Your BizKitHub API key (passed as GET parameter).

Key format: A 32-character string matching: ^(PROD|DEV_|ROOT)[A-Za-z0-9]{28}$
Prefixes: PROD (production key), DEV_ (individual developer), ROOT (system key with no limits). Learn more

ExamplePRODPGrFxpGEtrOZfuWhnoJohUYBXuOE
customerRealIpstringOptional

User IP address used for GEO/IP intelligence.

Accepted formats:

  • IPv4 dot-decimal, e.g. 1.1.1.1 (4 octets, 0–255, no leading zeros).
  • IPv6 as defined by RFC 4291 — full 2001:0db8:0000:0000:0000:0000:0000:0001, zero-compressed 2001:db8::1, IPv4-mapped ::ffff:1.2.3.4, or scoped literals. Both upper- and lower-case hex are accepted.

Server-side canonicalization (ipNormalize in core/src/lib/network/ipNormalize.ts):

  • Valid IPv4 is passed through verbatim.
  • Valid IPv6 is lowercased (RFC 5952 §4.3).
  • IPv4-mapped IPv6 ::ffff:X.X.X.X is unwrapped to plain IPv4 (RFC 4291 §2.5.5.2) so 1.2.3.4 and ::ffff:1.2.3.4 share one brj__geo_ip row.
  • Loopback aliases (::1, 0.0.0.0, localhost, empty string) collapse to 127.0.0.1.
  • Junk values that fail both IPv4 and IPv6 validation are silently rejected and replaced with 127.0.0.1 (loopback).

On the wire: every response returns the canonicalized form — clients can safely rely on lowercase IPv6 and the plain-IPv4 unwrap when de-duping or joining. Server-originated writers (activity log, session log, ban list) resolve the visitor IP via resolveClientIp / resolveClientIpOrNull — always native IPv6 on Vercel Edge (there is no auto-mapping to ::ffff:X.X.X.X).

Enrichment: the system resolves reverse DNS, geolocation, ASN, mobile/proxy/hosting/Tor flags via our VikiTron GEO/IP resolver for both address families. Learn more

Example1.1.1.1

Request body

application/json
messagestringRequired

Message body from the customer. At least 10 characters (rejects one-word noise). At most 5000 characters for messageFormat: text and 15000 for markdown (formatting syntax and links take room); a full report fits, spam floods do not.

Length: 10–15000
ExampleHello, how are you?
subjectstringOptional

Subject line for the support ticket.

ExampleRequest from Jan
noticestringOptional

Internal note (not visible to customer).

ExampleInternal notice
sendToEmailstringOptional

Contact email address.

The system validates the input as a standard email address and automatically applies normalization and canonicalization.

All API responses return the normalized form, and each email address is unique per organisation within the system.

Phone-only contacts: Since 2026-06-10 a contact may exist without an e-mail when it was registered only by phone (e.g. imports of phone-only records). Responses that expose such contacts use API_EMAIL_NULLABLE instead, where this field can be null. Endpoints that accept e-mail as input still require a valid value here — phone-only creation goes through admin-only import / BFF flows.

categorySlugstringOptional

Category slug for routing the ticket. By default the same slug is also assigned to the submitting contact as a contact group (new and existing contacts alike; a missing group is auto-created). If your website grants rights based on contact groups, pass assignCategoryGroup: false or use a category slug that is not used as a permission group.

Exampleoffer
assignCategoryGroupbooleanOptional

Whether categorySlug is also assigned to the contact as a contact group. Default true (historic behaviour). Pass false to only route the ticket and leave the contact groups untouched.

Default: true
customerEmailstringOptional

Contact email address.

The system validates the input as a standard email address and automatically applies normalization and canonicalization.

All API responses return the normalized form, and each email address is unique per organisation within the system.

Phone-only contacts: Since 2026-06-10 a contact may exist without an e-mail when it was registered only by phone (e.g. imports of phone-only records). Responses that expose such contacts use API_EMAIL_NULLABLE instead, where this field can be null. Endpoints that accept e-mail as input still require a valid value here — phone-only creation goes through admin-only import / BFF flows.

customerPhonestringOptional

Contact phone number in international (national) format.

Preferred format: +<country_code> <local_number>

  • Leading plus sign (+) is required
  • Followed by the country calling code (e.g. 420)
  • One space after the country code
  • Full local number without spaces

Example: +420 777123456
This format ensures unambiguous storage, validation, and compatibility with SMS, calling, and third-party integrations (e.g. Twilio, WhatsApp, CRM systems).

Example+420 777123456
customerFirstNamestringOptional
ExampleJan
customerLastNamestringOptional
ExampleBarášek
urgentbooleanOptional

Reporter's felt-urgency flag. Pass true when the contact form exposes an 'urgent for me' checkbox and the visitor ticked it. Persisted to pm__issue.user_urgency_hint and forwarded to the AI triage classifier as a soft input (never authoritative — content still decides the final priority). Keep unset / false for automated submissions.

Default: false
attachmentsstring[]Optional

Optional file attachments uploaded alongside the ticket. Send as multipart/form-data with repeated attachments parts. Policy: up to 5 files, max 10 MB each, max 25 MB combined. Only images, PDFs, plain text/CSV, Office and OpenDocument files are accepted — archives and executables are rejected via magic-byte detection even when the extension is renamed. Each accepted file is stored privately in core__blob and linked to the created issue via pm__issue_attachment.

Default: Files

Optional file attachments uploaded alongside the ticket. Send as multipart/form-data with repeated attachments parts. Policy: up to 5 files, max 10 MB each, max 25 MB combined. Only images, PDFs, plain text/CSV, Office and OpenDocument files are accepted — archives and executables are rejected via magic-byte detection even when the extension is renamed. Each accepted file is stored privately in core__blob and linked to the created issue via pm__issue_attachment.

inlineImagesstring[]Optional

Images embedded in a markdown message (messageFormat: markdown). The N-th part replaces the image source token bkh-inline-image:N in the message, e.g. ![Screenshot](bkh-inline-image:0). PNG, JPEG, WebP or GIF, max 5 MB each, max 10 images. Stored publicly (unguessable URL) so they render in the description everywhere, and also listed as ticket attachments. Unreferenced or failed images are dropped from the body.

Default: Files

Images embedded in a markdown message (messageFormat: markdown). The N-th part replaces the image source token bkh-inline-image:N in the message, e.g. ![Screenshot](bkh-inline-image:0). PNG, JPEG, WebP or GIF, max 5 MB each, max 10 images. Stored publicly (unguessable URL) so they render in the description everywhere, and also listed as ticket attachments. Unreferenced or failed images are dropped from the body.

branchSlugstringOptional

Branch the request is about (slug from /branch/list), when the visitor picked one. The ticket then appears in /support/my-issue-list of the branch technicians (unless it is confidential). An unknown or inactive slug is silently ignored and the ticket is created without a branch.

Length: 0–255
Exampleplzen-skvrnany
messageFormat"text" | "markdown"Optional

text (default): plain text, line breaks preserved. markdown: GitHub-flavoured markdown from a rich editor (headings, lists, code, tables, links, images); rendered through the same sanitizer as every ticket body.

Default: text

Response schema

1 status code documented

200Success
object | object
One of 2:
Variant 1
success"true"Required
issueKeystringOptional

Human-readable reference of the created ticket.

ExampleBIZKIT-123
externalIdstringOptional

Opaque 16-char ticket id. Grants read/reply access to the public ticket page, treat it like the link in the confirmation e-mail.

ExampleQr0MZ0vYnp8xMYgs
ticketUrlstringOptional

Canonical public ticket page. Redirect the submitter here after a successful submission.

Examplehttps://support.bizkithub.com/ticket/Qr0MZ0vYnp8xMYgs?locale=cs
Variant 2
success"false"Required
error"SUBMISSION_FAILED" | "TOO_MANY_ATTACHMENTS" | "ATTACHMENT_TOO_LARGE" | "ATTACHMENT_TOTAL_TOO_LARGE" | "UNSUPPORTED_ATTACHMENT_TYPE"Required
messagestringRequired

Human-readable explanation. SUBMISSION_FAILED is deliberately generic (anti-spam and infrastructure hiccups look identical from the outside). Attachment-related errors are specific so the UI can tell the reporter which file to drop. Show the string verbatim.

Response example

application/json
{
  "success": true,
  "issueKey": "BIZKIT-123",
  "externalId": "Qr0MZ0vYnp8xMYgs",
  "ticketUrl": "https://support.bizkithub.com/ticket/Qr0MZ0vYnp8xMYgs?locale=cs"
}

Request example

POST /api/v1/support/contact-form

post
curl -X POST "https://api.bizkithub.com/api/v1/support/contact-form?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE&customerRealIp=1.1.1.1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "message": "Hello, how are you?",
  "subject": "Request from Jan",
  "notice": "Internal notice",
  "sendToEmail": "[email protected]",
  "categorySlug": "offer",
  "assignCategoryGroup": true,
  "customerEmail": "[email protected]",
  "customerPhone": "+420 777123456",
  "customerFirstName": "Jan",
  "customerLastName": "Barášek",
  "urgent": false,
  "attachments": [
    "Files"
  ],
  "inlineImages": [
    "Files"
  ],
  "branchSlug": "plzen-skvrnany",
  "messageFormat": "text"
}'

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key