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

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. Must be at least 10 characters (rejects one-word noise) and at most 5000 characters (a full report fits, spam floods do not).

Length: 10–5000
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.

Examplejan@barasek.com
categorySlugstringOptional

Category slug for routing the ticket.

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

Examplejan@barasek.com
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

Response schema

1 status code documented

200Success
object | object
One of 2:
Variant 1
success"true"Required
Variant 2
success"false"Required
error"SUBMISSION_FAILED"Required
messagestringRequired

Human-readable, deliberately generic explanation (anti-spam rejection and infrastructure failure are indistinguishable from the outside). Show this verbatim in the UI.

Response example

application/json
{
  "success": true
}

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": "jan@barasek.com",
  "categorySlug": "offer",
  "customerEmail": "jan@barasek.com",
  "customerPhone": "+420 777123456",
  "customerFirstName": "Jan",
  "customerLastName": "Barášek",
  "urgent": false
}'

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key