Track a lead

curl --request POST \
  --url https://biq.li/api/v1/track/lead \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventName": "<string>",
  "customerExternalId": "<string>",
  "clickId": "<string>",
  "customerName": "<string>",
  "customerEmail": "jsmith@example.com",
  "customerAvatar": "<string>",
  "eventId": "<string>",
  "eventQuantity": 1,
  "metadata": {},
  "occurredAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://biq.li/api/v1/track/lead"

payload = {
    "eventName": "<string>",
    "customerExternalId": "<string>",
    "clickId": "<string>",
    "customerName": "<string>",
    "customerEmail": "jsmith@example.com",
    "customerAvatar": "<string>",
    "eventId": "<string>",
    "eventQuantity": 1,
    "metadata": {},
    "occurredAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    eventName: '<string>',
    customerExternalId: '<string>',
    clickId: '<string>',
    customerName: '<string>',
    customerEmail: 'jsmith@example.com',
    customerAvatar: '<string>',
    eventId: '<string>',
    eventQuantity: 1,
    metadata: {},
    occurredAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://biq.li/api/v1/track/lead', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/track/lead",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventName' => '<string>',
    'customerExternalId' => '<string>',
    'clickId' => '<string>',
    'customerName' => '<string>',
    'customerEmail' => 'jsmith@example.com',
    'customerAvatar' => '<string>',
    'eventId' => '<string>',
    'eventQuantity' => 1,
    'metadata' => [
        
    ],
    'occurredAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://biq.li/api/v1/track/lead"

	payload := strings.NewReader("{\n  \"eventName\": \"<string>\",\n  \"customerExternalId\": \"<string>\",\n  \"clickId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"eventQuantity\": 1,\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/track/lead")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventName\": \"<string>\",\n  \"customerExternalId\": \"<string>\",\n  \"clickId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"eventQuantity\": 1,\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/track/lead")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventName\": \"<string>\",\n  \"customerExternalId\": \"<string>\",\n  \"clickId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"eventQuantity\": 1,\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "event": {
    "id": "<string>",
    "eventName": "<string>",
    "type": "lead",
    "occurredAt": "2023-11-07T05:31:56Z"
  },
  "click": {
    "id": "<string>"
  },
  "link": {
    "id": "<string>",
    "shortUrl": "<string>",
    "destinationUrl": "<string>"
  },
  "customer": {
    "id": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "email": "jsmith@example.com",
    "avatar": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

POST

track

lead

Track a lead

curl --request POST \
  --url https://biq.li/api/v1/track/lead \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventName": "<string>",
  "customerExternalId": "<string>",
  "clickId": "<string>",
  "customerName": "<string>",
  "customerEmail": "jsmith@example.com",
  "customerAvatar": "<string>",
  "eventId": "<string>",
  "eventQuantity": 1,
  "metadata": {},
  "occurredAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://biq.li/api/v1/track/lead"

payload = {
    "eventName": "<string>",
    "customerExternalId": "<string>",
    "clickId": "<string>",
    "customerName": "<string>",
    "customerEmail": "jsmith@example.com",
    "customerAvatar": "<string>",
    "eventId": "<string>",
    "eventQuantity": 1,
    "metadata": {},
    "occurredAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    eventName: '<string>',
    customerExternalId: '<string>',
    clickId: '<string>',
    customerName: '<string>',
    customerEmail: 'jsmith@example.com',
    customerAvatar: '<string>',
    eventId: '<string>',
    eventQuantity: 1,
    metadata: {},
    occurredAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://biq.li/api/v1/track/lead', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/track/lead",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventName' => '<string>',
    'customerExternalId' => '<string>',
    'clickId' => '<string>',
    'customerName' => '<string>',
    'customerEmail' => 'jsmith@example.com',
    'customerAvatar' => '<string>',
    'eventId' => '<string>',
    'eventQuantity' => 1,
    'metadata' => [
        
    ],
    'occurredAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://biq.li/api/v1/track/lead"

	payload := strings.NewReader("{\n  \"eventName\": \"<string>\",\n  \"customerExternalId\": \"<string>\",\n  \"clickId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"eventQuantity\": 1,\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/track/lead")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventName\": \"<string>\",\n  \"customerExternalId\": \"<string>\",\n  \"clickId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"eventQuantity\": 1,\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/track/lead")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventName\": \"<string>\",\n  \"customerExternalId\": \"<string>\",\n  \"clickId\": \"<string>\",\n  \"customerName\": \"<string>\",\n  \"customerEmail\": \"jsmith@example.com\",\n  \"customerAvatar\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"eventQuantity\": 1,\n  \"metadata\": {},\n  \"occurredAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "event": {
    "id": "<string>",
    "eventName": "<string>",
    "type": "lead",
    "occurredAt": "2023-11-07T05:31:56Z"
  },
  "click": {
    "id": "<string>"
  },
  "link": {
    "id": "<string>",
    "shortUrl": "<string>",
    "destinationUrl": "<string>"
  },
  "customer": {
    "id": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "email": "jsmith@example.com",
    "avatar": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

Use this endpoint from a trusted server when a customer signs up, submits a qualified form, starts a trial, or completes another lead event.

Authentication and permission

Send a secret biqli_... workspace API key with Conversions: Write (conversions.create). Do not use a browser publishable key or call this endpoint from frontend code.

Authorization: Bearer biqli_your_workspace_api_key
Content-Type: application/json
Accept: application/json

The key selects the workspace. Do not send a workspace ID. Server tracking does not use browser origins or the allowed-hostname list.

Request

curl --request POST \
  --url https://biq.li/api/v1/track/lead \
  --header "Authorization: Bearer $BIQLI_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: lead_signup_customer_1842' \
  --header 'X-Biq-Client: acme-backend' \
  --header 'X-Biq-Client-Version: 1.4.0' \
  --data '{
    "clickId": "fGQimsCLcpoa",
    "eventId": "lead_signup_customer_1842",
    "eventName": "Signed up",
    "customerExternalId": "customer_1842",
    "customerName": "Ada Lovelace",
    "customerEmail": "ada@example.com",
    "eventQuantity": 1,
    "metadata": {
      "plan": "pro"
    },
    "occurredAt": "2026-09-12T22:35:02Z"
  }'

Field	Required	Description
`clickId`	Conditional	Biqli click ID from `bq_id` or client click tracking. You may omit it only when this workspace customer already has eligible attribution.
`eventName`	Yes	Lead name, from 1 to 255 characters.
`customerExternalId`	Yes	Stable customer ID from your system, from 1 to 100 characters.
`customerName`	No	Customer display name, up to 255 characters.
`customerEmail`	No	Valid customer email, up to 254 characters.
`customerAvatar`	No	HTTP or HTTPS avatar URL, up to 2,048 characters.
`eventId`	No	Stable event identifier. Use 1 to 100 safe identifier characters.
`eventQuantity`	No	Positive integer from 1 to 100. Defaults to `1`.
`metadata`	No	JSON object, up to 16 KB, 50 keys, 100 values, and five nested levels. Keys contain 1 to 64 characters and cannot be numeric-only.
`occurredAt`	No	ISO 8601 event time. It must be within seven days in the past and five minutes in the future.

The attributed click must be active, unexpired, and belong to the API key’s workspace. A click from another workspace returns 404 resource_not_found.

Idempotency

Send a stable Idempotency-Key on every retry. Also send a stable eventId when your system has one. Repeating the same identifier and payload returns the original 201 response with Idempotency-Replayed: true and creates no new event, realtime update, or webhook delivery. Reusing an idempotency or event identifier with different data returns 409 idempotency_conflict. Idempotency records are retained for seven days; the event identifier remains durably unique within its workspace and source.

Response

{
  "event": {
    "id": "biq_lev_01M2BW50V1MJDD4KPZ394GXGC5",
    "eventName": "Signed up",
    "type": "lead",
    "occurredAt": "2026-09-12T22:35:02+00:00"
  },
  "click": {"id": "fGQimsCLcpoa"},
  "link": {
    "id": "biq_lnk_01M2BVVED2HDH0JVM5HV9WQ2F6",
    "shortUrl": "https://biq.li/3bKxigL",
    "destinationUrl": "https://example.com/signup"
  },
  "customer": {
    "id": "biq_cus_01M2BW50TQD96C0QPCM6Z6WZNF",
    "externalId": "customer_1842",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "avatar": null
  },
  "request_id": "8259fc91-99f4-4f96-bfc0-1be9c208a91e"
}

The response uses public IDs only. Deleted links continue to resolve through their preserved conversion snapshot.

Errors

Status	Code	Meaning
`401`	`invalid_token`	The workspace API key is missing, invalid, revoked, or the wrong credential type.
`403`	`insufficient_scope`	The key lacks `conversions.create`.
`403`	`tracking_disabled`	Conversion tracking is unavailable or disabled for the workspace.
`404`	`resource_not_found`	The click is expired, missing, or belongs to another workspace.
`405`	`method_not_allowed`	This endpoint only accepts `POST`.
`409`	`idempotency_conflict`	An idempotency or event identifier was reused with different data.
`422`	`attribution_required`	Neither a valid `clickId` nor existing customer attribution was available.
`422`	`validation_error`	The JSON body, fields, metadata, or event time is invalid.
`429`	`rate_limit_exceeded`	The workspace exceeded its API request allowance.

Authentication, errors, rate-limit headers, and request IDs follow the shared API conventions.

Authorizations

Authorization

string

header

required

A workspace API key beginning with biqli_.

Headers

Idempotency-Key

string

Stable retry key. Reuse only for the same logical request and payload.

Required string length: 1 - 255

X-Biq-Client

string

Integration name recorded in API diagnostics.

Maximum string length: 64

X-Biq-Client-Version

string

Integration version recorded in API diagnostics.

Maximum string length: 64

X-Biq-Request-Id

string

Caller-generated request identifier for tracing.

Required string length: 1 - 100

Pattern: ^[A-Za-z0-9._:-]+$

Body

application/json

eventName

string

required

Required string length: 1 - 255

customerExternalId

string

required

Required string length: 1 - 100

clickId

string | null

Required string length: 1 - 100

Pattern: ^[A-Za-z0-9_-]+$

customerName

string | null

Maximum string length: 255

customerEmail

string<email> | null

Maximum string length: 254

customerAvatar

string<uri> | null

Maximum string length: 2048

Pattern: ^https?://

eventId

string | null

Required string length: 1 - 100

Pattern: ^[A-Za-z0-9](?:[A-Za-z0-9._:-]*[A-Za-z0-9])?$

eventQuantity

integer | null

default:1

Required range: 1 <= x <= 100

metadata

object | null

occurredAt

string<date-time> | null

Pattern: Z$

Response

Lead created or idempotently replayed.

event

object

required

Show child attributes

click

object

required

Show child attributes

link

object | null

required

Show child attributes

customer

object

required

Show child attributes

request_id

string

required

GETTING STARTED

SDKs

BIQLI LINKS API

Track a lead

Authentication and permission

Request

Idempotency

Response

Errors

Authorizations

Headers

Body

Response

​Authentication and permission

​Request

​Idempotency

​Response

​Errors

Authorizations

Headers

Body

Response

Authentication and permission

Request

Idempotency

Response

Errors