{ "openapi": "3.1.0", "info": { "title": "Hoko API", "version": "0.0.1", "description": "REST API for creating short links, managing campaign metadata, reading analytics, and recording lead and sale conversions." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://hoko.to", "description": "Production" } ], "tags": [ { "name": "Links" }, { "name": "Collections" }, { "name": "Tags" }, { "name": "Partners" }, { "name": "Customers" }, { "name": "Analytics" }, { "name": "Conversion Tracking" } ], "paths": { "/api/links": { "get": { "tags": [ "Links" ], "operationId": "listLinks", "summary": "List links", "description": "Retrieves links by ID, external ID, tenant ID, or partner ID. Requires the `linksRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by resource ID." }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by external ID." }, { "name": "tenantId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by tenant ID." }, { "name": "partnerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by partner ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Links returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Link" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Links" ], "operationId": "createLinks", "summary": "Create links", "description": "Creates one or more links. Requires the `linksWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/LinkCreate" } } } } }, "responses": { "201": { "description": "Links created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Link" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Links" ], "operationId": "upsertLinks", "summary": "Create or update links", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `linksWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/LinkUpsert" } } } } }, "responses": { "200": { "description": "Links upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Link" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Links" ], "operationId": "deleteLinks", "summary": "Delete links", "description": "Soft-deletes one or more links by ID. Requires the `linksWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } }, "responses": { "200": { "description": "Links deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/collections": { "get": { "tags": [ "Collections" ], "operationId": "listCollections", "summary": "List collections", "description": "Requires the `collectionsRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by resource ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Collections returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Collection" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Collections" ], "operationId": "createCollections", "summary": "Create collections", "description": "Creates one or more records. Requires the `collectionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/CollectionCreate" } } } } }, "responses": { "201": { "description": "Collections created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Collection" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Collections" ], "operationId": "upsertCollections", "summary": "Create or update collections", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `collectionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/CollectionUpsert" } } } } }, "responses": { "200": { "description": "Collections upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Collection" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Collections" ], "operationId": "deleteCollections", "summary": "Delete collections", "description": "Soft-deletes one or more records by ID. Requires the `collectionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } }, "responses": { "200": { "description": "Collections deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/tags": { "get": { "tags": [ "Tags" ], "operationId": "listTags", "summary": "List tags", "description": "Requires the `tagsRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by resource ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Tags returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Tag" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Tags" ], "operationId": "createTags", "summary": "Create tags", "description": "Creates one or more records. Requires the `tagsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/TagCreate" } } } } }, "responses": { "201": { "description": "Tags created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Tag" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Tags" ], "operationId": "upsertTags", "summary": "Create or update tags", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `tagsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/TagUpsert" } } } } }, "responses": { "200": { "description": "Tags upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Tag" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Tags" ], "operationId": "deleteTags", "summary": "Delete tags", "description": "Soft-deletes one or more records by ID. Requires the `tagsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } }, "responses": { "200": { "description": "Tags deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/partners": { "get": { "tags": [ "Partners" ], "operationId": "listPartners", "summary": "List partners", "description": "Requires the `partnersRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by resource ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Partners returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Partner" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Partners" ], "operationId": "createPartners", "summary": "Create partners", "description": "Creates one or more records. Requires the `partnersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/PartnerCreate" } } } } }, "responses": { "201": { "description": "Partners created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Partner" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "put": { "tags": [ "Partners" ], "operationId": "upsertPartners", "summary": "Create or update partners", "description": "Entries with an `id` are updated; entries without an `id` are inserted. Requires the `partnersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/PartnerUpsert" } } } } }, "responses": { "200": { "description": "Partners upserted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Partner" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Partners" ], "operationId": "deletePartners", "summary": "Delete partners", "description": "Soft-deletes one or more records by ID. Requires the `partnersWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } } }, "responses": { "200": { "description": "Partners deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "deletedIds" ], "properties": { "deletedIds": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string", "format": "uuid" } } } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/customers": { "get": { "tags": [ "Customers" ], "operationId": "listCustomers", "summary": "List customers", "description": "Retrieves customers by ID or external ID. Requires the `customersRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by resource ID." }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by customer external ID." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Customers returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Customer" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/analytics": { "get": { "tags": [ "Analytics" ], "operationId": "listClicks", "summary": "List click analytics", "description": "Retrieves click records by link, partner, or date range. Requires the `analyticsRead` scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "linkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by link ID." }, { "name": "partnerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter by partner ID." }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive ISO date-time lower bound." }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive ISO date-time upper bound." }, { "name": "take", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 50 }, "description": "Number of records to return." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of records to skip." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Clicks returned.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Click" } }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/track/lead": { "post": { "tags": [ "Conversion Tracking" ], "operationId": "trackLead", "summary": "Track a lead conversion", "description": "Creates a lead event and upserts the customer. Requires the `conversionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadTrackRequest" } } } }, "responses": { "201": { "description": "Lead tracked.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadTrackResponse" }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/track/sale": { "post": { "tags": [ "Conversion Tracking" ], "operationId": "trackSale", "summary": "Track a sale conversion", "description": "Creates a sale event and upserts the customer. Requires the `conversionsWrite` scope.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleTrackRequest" } } } }, "responses": { "201": { "description": "Sale tracked.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaleTrackResponse" }, "message": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] } } } } } }, "400": { "description": "Invalid request body, query string, or JSON payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "API key is missing the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Hoko API key. Send as `Authorization: Bearer `." } }, "headers": { "XRateLimitLimit": { "description": "Maximum requests allowed per minute for the workspace plan.", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requests remaining in the current rate-limit window.", "schema": { "type": "integer" } }, "XRateLimitReset": { "description": "Unix timestamp, in seconds, when the current window resets.", "schema": { "type": "integer" } } }, "schemas": { "LocalizedMessage": { "type": "object", "required": [ "en", "ar" ], "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/LocalizedMessage" } ] }, "missingScopes": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "string" } }, "retryAfter": { "type": "integer", "minimum": 0 } } }, "Utm": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "medium": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "term": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "referral": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "GeoTargeting": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Z]{2}$" }, "additionalProperties": { "type": "string", "format": "uri" } }, "Link": { "type": "object", "required": [ "id", "url", "shortUrl", "qrCode", "collectionId", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "shortUrl": { "type": "string", "format": "uri" }, "qrCode": { "type": "string", "format": "uri" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "utm": { "oneOf": [ { "$ref": "#/components/schemas/Utm" }, { "type": "null" } ] }, "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiredUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "password": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "cloaked": { "type": "boolean" }, "ios": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "android": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "geo": { "oneOf": [ { "$ref": "#/components/schemas/GeoTargeting" }, { "type": "null" } ] }, "collectionId": { "type": "string", "format": "uuid" }, "externalId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tenantId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "partnerId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "LinkCreate": { "type": "object", "required": [ "url", "collectionId" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string", "format": "uri" }, "utm": { "$ref": "#/components/schemas/Utm" }, "expiresAt": { "type": "string", "format": "date-time" }, "expiredUrl": { "type": "string", "format": "uri" }, "password": { "type": "string" }, "cloaked": { "type": "boolean", "default": false }, "ios": { "type": "string", "format": "uri" }, "android": { "type": "string", "format": "uri" }, "geo": { "$ref": "#/components/schemas/GeoTargeting" }, "collectionId": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "tenantId": { "type": "string" }, "partnerId": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "LinkUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "utm": { "$ref": "#/components/schemas/Utm" }, "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiredUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "password": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "cloaked": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ios": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "android": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "geo": { "oneOf": [ { "$ref": "#/components/schemas/GeoTargeting" }, { "type": "null" } ] }, "collectionId": { "type": "string", "format": "uuid" }, "externalId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tenantId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "partnerId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "additionalProperties": false }, "LinkUpsert": { "oneOf": [ { "$ref": "#/components/schemas/LinkCreate" }, { "$ref": "#/components/schemas/LinkUpdate" } ] }, "Collection": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CollectionCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "additionalProperties": false }, "CollectionUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "CollectionUpsert": { "oneOf": [ { "$ref": "#/components/schemas/CollectionCreate" }, { "$ref": "#/components/schemas/CollectionUpdate" } ] }, "Tag": { "type": "object", "required": [ "id", "name", "color" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ] } } }, "TagCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "default": "slate" } }, "additionalProperties": false }, "TagUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ] } }, "additionalProperties": false }, "TagUpsert": { "oneOf": [ { "$ref": "#/components/schemas/TagCreate" }, { "$ref": "#/components/schemas/TagUpdate" } ] }, "Partner": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PartnerCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } }, "additionalProperties": false }, "PartnerUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "PartnerUpsert": { "oneOf": [ { "$ref": "#/components/schemas/PartnerCreate" }, { "$ref": "#/components/schemas/PartnerUpdate" } ] }, "Customer": { "type": "object", "required": [ "id", "externalId", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "avatar": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "name": { "type": "string" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Click": { "type": "object", "required": [ "id", "linkId", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "linkId": { "type": "string", "format": "uuid" }, "partnerId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "visitorId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "visitorSessionId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "destination": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "shortId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "oneOf": [ { "$ref": "#/components/schemas/Utm" }, { "type": "null" } ] }, "externalId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tenantId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "expired": { "type": "boolean" }, "secured": { "type": "boolean" }, "scanned": { "type": "boolean" }, "geoTargeted": { "type": "boolean" }, "iosTargeted": { "type": "boolean" }, "androidTargeted": { "type": "boolean" }, "origin": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "pathname": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "search": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserLanguageCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserLanguageRegion": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "osName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceVendor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceModel": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceType": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "ipAddress": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "continent": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "mobile": { "type": "boolean" }, "proxy": { "type": "boolean" }, "hosting": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "LeadTrackRequest": { "type": "object", "required": [ "clickId", "eventName", "customerExternalId", "customerName" ], "properties": { "clickId": { "type": "string", "description": "Click ID, or an empty string to use deferred tracking from the customer history." }, "eventName": { "type": "string", "minLength": 1, "maxLength": 255 }, "customerExternalId": { "type": "string", "minLength": 1, "maxLength": 100 }, "customerName": { "type": "string", "minLength": 1, "maxLength": 100 }, "customerEmail": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "customerAvatar": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "SaleTrackRequest": { "type": "object", "required": [ "customerExternalId", "amount", "customerName" ], "properties": { "customerExternalId": { "type": "string", "minLength": 1, "maxLength": 100 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "default": "usd" }, "eventName": { "type": "string", "maxLength": 255, "default": "Purchase" }, "metadata": { "type": "object", "additionalProperties": true }, "leadEventName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "clickId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "type": "string", "minLength": 1, "maxLength": 100 }, "customerEmail": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "customerAvatar": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "additionalProperties": false }, "LeadTrackResponse": { "type": "object", "properties": { "click": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "link": { "$ref": "#/components/schemas/Link" }, "lead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventName": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "customer": { "$ref": "#/components/schemas/Customer" } } }, "SaleTrackResponse": { "type": "object", "properties": { "click": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, { "type": "null" } ] }, "link": { "$ref": "#/components/schemas/Link" }, "sale": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventName": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "customer": { "$ref": "#/components/schemas/Customer" } } } } } }