Developers

API reference

Manage QR codes, links, leads and products, and read scan events. Authenticate with `Authorization: Bearer qriva_…`. Keys are created by workspace admins under Integrations → API and can be limited to specific resources. Every response carries `X-Qriva-Api-Version`.

Base URL https://qr-iva.com/api/v1Version 2026-09-13OpenAPI 3.1 JSON18 endpoints

Authentication & limits

Send Authorization: Bearer qriva_…. Admins create keys under Integrations → API and can limit a key to resources, e.g. contacts:read.
600 (Pro), 3,000 (Company) or 20,000 (Enterprise) requests per hour per key (429 when exceeded).
Lists take limit (1–200) and offset, and return total.
Errors look like {"error":{"code","message"}}.
Writes to leads accept Idempotency-Key; a repeat within 24 h returns the first response.

Webhooks

Signed POSTs to your endpoint. Headers: X-Qriva-Event, X-Qriva-Delivery (same on every retry), X-Qriva-Timestamp, X-Qriva-Signature = hex HMAC-SHA256 of `${timestamp}.${raw body}` with your endpoint secret; during a secret rotation also X-Qriva-Signature-Previous. Respond 2xx within 8 seconds. Failures are retried 6 times over about 21 hours.

Events: scan.createdlead.capturedlead.status_changedlead.assignedlead.tag_addedautomation.actioncode.createdcode.updatedalert.raisedproduct.scanned

Codes

GET/codesscope codes:read

List QR codes

Parameter	In	Description
status	query	active \| paused \| archived
tag	query	Only codes with this tag
q	query	Name contains
limit	query	integer
offset	query	integer

Responses: 200 Codes, newest first401 Missing or invalid key.403 The key lacks the scope this call needs.429 Rate limit: 600 requests per hour per key.

cURL

curl -X GET "https://qr-iva.com/api/v1/codes" \
  -H "Authorization: Bearer $QRIVA_KEY"

POST/codesscope codes:write

Create a dynamic QR code

Body field	Type	Notes
name *	string
destination *	string, uri
slug	string
tags	array

Responses: 201 Created401 Missing or invalid key.403 The key lacks the scope this call needs.422 The body failed validation; the message says which field.429 Rate limit: 600 requests per hour per key.

cURL

curl -X POST "https://qr-iva.com/api/v1/codes" \
  -H "Authorization: Bearer $QRIVA_KEY" \
  -H "Content-Type: application/json" -d '{…}'

GET/codes/{id}scope codes:read

Get a QR code

Parameter	In	Description
id *	path	string, uuid

Responses: 200 The code401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.

cURL

curl -X GET "https://qr-iva.com/api/v1/codes/ID" \
  -H "Authorization: Bearer $QRIVA_KEY"

PATCH/codes/{id}scope codes:write

Repoint or rename a code, pause or archive it

Parameter	In	Description
id *	path	string, uuid

Body field	Type	Notes
name	string
destination	string, uri
status	active \| paused \| archived
tags	array

Responses: 200 Updated401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.422 The body failed validation; the message says which field.

cURL

curl -X PATCH "https://qr-iva.com/api/v1/codes/ID" \
  -H "Authorization: Bearer $QRIVA_KEY" \
  -H "Content-Type: application/json" -d '{…}'

DELETE/codes/{id}scope codes:write

Archive a code (printed codes keep resolving to a holding page)

Parameter	In	Description
id *	path	string, uuid

Responses: 200 Archived401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.

cURL

curl -X DELETE "https://qr-iva.com/api/v1/codes/ID" \
  -H "Authorization: Bearer $QRIVA_KEY"

GET/codes/{id}/imagescope codes:read

Download the artwork

Parameter	In	Description
id *	path	string, uuid
format	query	svg \| png \| jpg \| pdf

Responses: 200 The image401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.

cURL

curl -X GET "https://qr-iva.com/api/v1/codes/ID/image" \
  -H "Authorization: Bearer $QRIVA_KEY"

Links

GET/linksscope links:read

List short links

Parameter	In	Description
status	query	active \| paused \| archived
tag	query	Only links with this tag
q	query	Name contains
limit	query	integer
offset	query	integer

Responses: 200 Links401 Missing or invalid key.403 The key lacks the scope this call needs.429 Rate limit: 600 requests per hour per key.

cURL

curl -X GET "https://qr-iva.com/api/v1/links" \
  -H "Authorization: Bearer $QRIVA_KEY"

POST/linksscope links:write

Create a short link

Body field	Type	Notes
name *	string
destination *	string, uri	http(s) URL; screened against threat lists before it is saved
status	active \| paused \| archived
slug	string	Custom back-half, 3–32 characters
tags	array
utm	object
starts_at	string, date-time
expires_at	string, date-time
expired_url	string, uri
scan_limit	integer \| null
scan_limit_unique	boolean
limit_url	string, uri
safe_preview	boolean
password	string \| null

cURL

curl -X POST "https://qr-iva.com/api/v1/links" \
  -H "Authorization: Bearer $QRIVA_KEY" \
  -H "Content-Type: application/json" -d '{…}'

GET/links/{id}scope links:read

Get a link

Parameter	In	Description
id *	path	string, uuid

Responses: 200 The link401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.

cURL

curl -X GET "https://qr-iva.com/api/v1/links/ID" \
  -H "Authorization: Bearer $QRIVA_KEY"

PATCH/links/{id}scope links:write

Change any link setting

Parameter	In	Description
id *	path	string, uuid

Body field	Type	Notes
name	string
destination	string, uri	http(s) URL; screened against threat lists before it is saved
status	active \| paused \| archived
slug	string	Custom back-half, 3–32 characters
tags	array
utm	object
starts_at	string, date-time
expires_at	string, date-time
expired_url	string, uri
scan_limit	integer \| null
scan_limit_unique	boolean
limit_url	string, uri
safe_preview	boolean
password	string \| null

Responses: 200 Updated401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.422 The body failed validation; the message says which field.

cURL

curl -X PATCH "https://qr-iva.com/api/v1/links/ID" \
  -H "Authorization: Bearer $QRIVA_KEY" \
  -H "Content-Type: application/json" -d '{…}'

DELETE/links/{id}scope links:write

Archive a link

Parameter	In	Description
id *	path	string, uuid

Responses: 200 Archived401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.

cURL

curl -X DELETE "https://qr-iva.com/api/v1/links/ID" \
  -H "Authorization: Bearer $QRIVA_KEY"

Scans

GET/scansscope scans:read

Scan and page events, oldest first

Parameter	In	Description
code_id	query	Filter by code
link_id	query	Filter by link
product_id	query	Filter by product
country	query	ISO country code
source	query	qr \| link \| page \| product
from	query	ISO date-time, inclusive
to	query	ISO date-time, inclusive
limit	query	integer
offset	query	integer

Responses: 200 Events401 Missing or invalid key.403 The key lacks the scope this call needs.429 Rate limit: 600 requests per hour per key.

cURL

curl -X GET "https://qr-iva.com/api/v1/scans" \
  -H "Authorization: Bearer $QRIVA_KEY"

Leads

GET/contactsscope contacts:read

List leads

Parameter	In	Description
form_id	query	Only responses to this form
since	query	Created at or after (ISO date-time)
status	query	new \| contacted \| qualified \| won \| lost \| spam
tag	query	Only leads with this tag
email	query	Exact e-mail (case-insensitive)
limit	query	integer
offset	query	integer

Responses: 200 Leads, newest first; merged duplicates are left out401 Missing or invalid key.403 The key lacks the scope this call needs.429 Rate limit: 600 requests per hour per key.

cURL

curl -X GET "https://qr-iva.com/api/v1/contacts" \
  -H "Authorization: Bearer $QRIVA_KEY"

POST/contactsscope contacts:write

Add a lead

A lead with the same e-mail or phone as an existing one updates that lead (fills empty details, adds tags) and returns 200 — unless `on_duplicate` is `create`. New leads (201) trigger automations. Send `Idempotency-Key` to make retries safe.

Parameter	In	Description
Idempotency-Key	header	Repeats within 24 hours return the first response

Body field	Type	Notes
name	string
email	string, email
phone	string
company	string
country	string	Two-letter code
city	string
data	object
tags	array
status	new \| contacted \| qualified \| won \| lost \| spam
consent	boolean
consent_text	string	Required when consent is true: what the person agreed to, where and when
on_duplicate	merge \| create

Responses: 200 Existing lead updated201 Created401 Missing or invalid key.403 The key lacks the scope this call needs.409 Idempotency-Key reused with a different body.422 The body failed validation; the message says which field.429 Rate limit: 600 requests per hour per key.

cURL

curl -X POST "https://qr-iva.com/api/v1/contacts" \
  -H "Authorization: Bearer $QRIVA_KEY" \
  -H "Content-Type: application/json" -d '{…}'

GET/contacts/{id}scope contacts:read

Get a lead

Parameter	In	Description
id *	path	string, uuid

Responses: 200 The lead301 Merged into another lead; `merged_into` gives its id401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.

cURL

curl -X GET "https://qr-iva.com/api/v1/contacts/ID" \
  -H "Authorization: Bearer $QRIVA_KEY"

PATCH/contacts/{id}scope contacts:write

Update a lead's workflow

Changes are recorded in the lead's history and fire automations (status changed, assigned, tag added).

Parameter	In	Description
id *	path	string, uuid

Body field	Type	Notes
status	new \| contacted \| qualified \| won \| lost \| spam
owner_email	string \| null, email
follow_up_at	string \| null, date-time
add_tags	array
remove_tags	array
note	string

Responses: 200 Updated401 Missing or invalid key.403 The key lacks the scope this call needs.404 Not found in this workspace.422 The body failed validation; the message says which field.

cURL

curl -X PATCH "https://qr-iva.com/api/v1/contacts/ID" \
  -H "Authorization: Bearer $QRIVA_KEY" \
  -H "Content-Type: application/json" -d '{…}'

Products

GET/productsscope products:read

List products

Parameter	In	Description
gtin	query	Exact GTIN
limit	query	integer
offset	query	integer

Responses: 200 Products401 Missing or invalid key.403 The key lacks the scope this call needs.429 Rate limit: 600 requests per hour per key.

cURL

curl -X GET "https://qr-iva.com/api/v1/products" \
  -H "Authorization: Bearer $QRIVA_KEY"

POST/productsscope products:write

Create a product (GS1 Digital Link)

Body field	Type	Notes
gtin *	string	GTIN-8/12/13/14 with a valid check digit
name *	string
brand	string
batch	string
serial	string

cURL

curl -X POST "https://qr-iva.com/api/v1/products" \
  -H "Authorization: Bearer $QRIVA_KEY" \
  -H "Content-Type: application/json" -d '{…}'