> ## Documentation Index > Fetch the complete documentation index at: https://help.awin.com/llms.txt > Use this file to discover all available pages before exploring further. # Create tracking links > Generates a tracking link to a page on the advertiser's site, and optionally a short link to it. Use it to build links for promotions, newsletters or publisher content without the Link Builder UI. Nothing is stored: the same request returns the same tracking link. When `shorten` is `true`, each successful call creates a new short link and uses up part of the account's short link quota, including when a request is retried. If the short link cannot be created, the whole request fails and no tracking link is returned. When the short link quota is used up, the request fails with `429` and code `LINK_SHORTENER_QUOTA_EXCEEDED`, and `Retry-After` says when the quota resets. When the short link service is temporarily unavailable, the request fails with `503`. When `publisherId` is supplied, the publisher must be actively joined to the advertiser; otherwise the request fails with `422`, and `errors[].pointer` names the field. The caller must belong to the advertiser account and hold at least the Viewer role on it; otherwise the request is rejected with `403`. ## OpenAPI ````json POST /v1/advertisers/{advertiserId}/tracking-links { "openapi": "3.0.3", "info": { "title": "Awin Public API", "version": "0.1.0" }, "servers": [ { "url": "https://api.awin.com/public", "description": "Production" } ], "tags": [ { "name": "Advertisers", "description": "Endpoints for advertiser accounts." }, { "name": "Advertisers > Partnerships", "description": "Advertiser partnerships with publishers." }, { "name": "Advertisers > Tracking links", "description": "Advertiser tracking links." }, { "name": "Advertisers > Billing", "description": "Advertiser billing and prepayments." }, { "name": "Publishers", "description": "Endpoints for publisher accounts." }, { "name": "Publishers > Partnerships", "description": "Publisher partnerships with advertisers." }, { "name": "Publishers > Transactions", "description": "Publisher transactions." }, { "name": "Publishers > Payments", "description": "Publisher payments and payment details." } ], "paths": { "/v1/advertisers/{advertiserId}/tracking-links": { "x-awin-owner": "hqteamraptor", "parameters": [ { "$ref": "#/components/parameters/AdvertiserId" } ], "post": { "tags": [ "Advertisers > Tracking links" ], "operationId": "createAdvertiserTrackingLink", "x-awin-audience": "public", "summary": "Create tracking links", "description": "Generates a tracking link to a page on the advertiser's site, and optionally a short link to it. Use it to build links for promotions, newsletters or publisher content without the Link Builder UI.\n\nNothing is stored: the same request returns the same tracking link. When `shorten` is `true`, each successful call creates a new short link and uses up part of the account's short link quota, including when a request is retried. If the short link cannot be created, the whole request fails and no tracking link is returned. When the short link quota is used up, the request fails with `429` and code `LINK_SHORTENER_QUOTA_EXCEEDED`, and `Retry-After` says when the quota resets. When the short link service is temporarily unavailable, the request fails with `503`.\n\nWhen `publisherId` is supplied, the publisher must be actively joined to the advertiser; otherwise the request fails with `422`, and `errors[].pointer` names the field.\n\nThe caller must belong to the advertiser account and hold at least the Viewer role on it; otherwise the request is rejected with `403`.", "x-awin-public-api-authorization": { "accountType": "advertiser", "minRole": "userViewer" }, "requestBody": { "$ref": "#/components/requestBodies/TrackingLinkCreate" }, "responses": { "200": { "description": "The tracking link, and the short link when requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingLink" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "The request body is not a JSON object, or one or more fields are missing, not declared, empty, `null`, or have the wrong type or format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" }, "examples": { "invalidPublisherId": { "summary": "publisherId is not a string of digits", "value": { "type": "https://help.awin.com/apis/error", "title": "Bad Request", "status": 400, "detail": "One or more fields failed validation", "code": "VALIDATION_FAILED", "errors": [ { "pointer": "/publisherId", "detail": "publisherId must be a string of digits" } ] } }, "invalidDestinationUrl": { "summary": "destinationUrl is not a valid URL", "value": { "type": "https://help.awin.com/apis/error", "title": "Bad Request", "status": 400, "detail": "One or more fields failed validation", "code": "VALIDATION_FAILED", "errors": [ { "pointer": "/destinationUrl", "detail": "destinationUrl must be a valid URL" } ] } }, "missingDestinationUrl": { "summary": "destinationUrl is missing", "value": { "type": "https://help.awin.com/apis/error", "title": "Bad Request", "status": 400, "detail": "One or more fields failed validation", "code": "VALIDATION_FAILED", "errors": [ { "pointer": "/destinationUrl", "detail": "destinationUrl is required" } ] } }, "unexpectedField": { "summary": "The body contains a field that is not declared", "value": { "type": "https://help.awin.com/apis/error", "title": "Bad Request", "status": 400, "detail": "One or more fields failed validation", "code": "VALIDATION_FAILED", "errors": [ { "pointer": "/mobileApp", "detail": "mobileApp is not allowed" } ] } }, "unexpectedParameter": { "summary": "trackingParameters contains a key other than campaign and clickref", "value": { "type": "https://help.awin.com/apis/error", "title": "Bad Request", "status": 400, "detail": "One or more fields failed validation", "code": "VALIDATION_FAILED", "errors": [ { "pointer": "/trackingParameters", "detail": "trackingParameters contains a parameter that is not allowed" } ] } }, "emptyCampaign": { "summary": "trackingParameters.campaign is an empty string", "value": { "type": "https://help.awin.com/apis/error", "title": "Bad Request", "status": 400, "detail": "One or more fields failed validation", "code": "VALIDATION_FAILED", "errors": [ { "pointer": "/trackingParameters/campaign", "detail": "trackingParameters/campaign must not be empty" } ] } }, "invalidBody": { "summary": "The request body is not a JSON object", "value": { "type": "https://help.awin.com/apis/error", "title": "Bad Request", "status": 400, "detail": "The request body must be a valid JSON object", "code": "VALIDATION_FAILED" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "The request is well formed but breaks a business rule: the publisher is not joined to the advertiser, the tracking link is too long to shorten, or the destination URL is not supported for this advertiser.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" }, "examples": { "publisherNotJoined": { "summary": "The publisher is not joined to the advertiser", "value": { "type": "https://help.awin.com/apis/error", "title": "Unprocessable Content", "status": 422, "detail": "The publisher is not joined to this advertiser", "code": "BUSINESS_RULE_VIOLATION", "errors": [ { "pointer": "/publisherId", "detail": "publisherId must be a publisher joined to this advertiser" } ] } }, "urlTooLong": { "summary": "The tracking link is too long to shorten", "value": { "type": "https://help.awin.com/apis/error", "title": "Unprocessable Content", "status": 422, "detail": "The tracking link is too long to be shortened", "code": "BUSINESS_RULE_VIOLATION", "errors": [ { "pointer": "/destinationUrl", "detail": "destinationUrl is too long to be shortened" } ] } }, "destinationNotSupported": { "summary": "The destination URL is not supported for this advertiser", "value": { "type": "https://help.awin.com/apis/error", "title": "Unprocessable Content", "status": 422, "detail": "The tracking link could not be generated for this destination URL", "code": "BUSINESS_RULE_VIOLATION", "errors": [ { "pointer": "/destinationUrl", "detail": "destinationUrl is not supported for this advertiser" } ] } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "security": [ { "patBearer": [] } ] } } }, "components": { "parameters": { "AdvertiserId": { "name": "advertiserId", "in": "path", "required": true, "description": "Identifier of the advertiser account.", "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "1001" } } }, "requestBodies": { "TrackingLinkCreate": { "description": "The tracking link to create", "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "destinationUrl" ], "properties": { "destinationUrl": { "type": "string", "minLength": 1, "description": "The page on the advertiser's site the tracking link sends the visitor to. The scheme is optional.", "example": "https://www.example.com/products/123" }, "publisherId": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Identifier of the publisher the link is generated for, as a string of digits. The publisher must be actively joined to the advertiser; otherwise the request fails with `422`. When omitted, the link contains a placeholder that each publisher replaces with their own identifier. Omit the field rather than sending `null`, which fails validation.", "example": "45628" }, "trackingParameters": { "type": "object", "additionalProperties": false, "description": "Optional tracking parameters added to the link. Only `campaign` and `clickref` are accepted; any other key fails validation. Omit the field rather than sending `null`, which fails validation.", "properties": { "campaign": { "type": "string", "minLength": 1, "description": "Campaign name, reported against the click.", "example": "summer-sale" }, "clickref": { "type": "string", "minLength": 1, "description": "Click reference, reported against the click.", "example": "banner-top" } } }, "shorten": { "type": "boolean", "default": false, "description": "When `true`, the response also contains a short link to the tracking link. Each short link uses up part of the account's daily short link quota. Only links of up to 2000 characters can be shortened: if the destination URL or the generated tracking link is longer, the request fails with `422`. Must be a JSON boolean; strings such as `\"true\"` fail validation.", "example": true } } } } } } }, "schemas": { "TrackingLink": { "type": "object", "description": "A tracking link for an advertiser, and optionally a short link to it.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "readOnly": true, "description": "The tracking link. Clicks on it are tracked and the visitor is sent to the destination URL.", "example": "https://www.awin1.com/cread.php?awinmid=1001&awinaffid=!!!id!!!&campaign=summer-sale&ued=https%3A%2F%2Fwww.example.com%2Fproducts%2F123" }, "shortUrl": { "type": "string", "format": "uri", "readOnly": true, "description": "A short link that redirects to `url`. Present only when the request set `shorten` to `true`; absent otherwise.", "example": "https://tidd.ly/3xAmPlE" } } }, "ValidationProblem": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "description": "A problem detail carrying the RFC 9457 extension member `errors`, used where a request fails validation on one or more specific fields.", "properties": { "errors": { "type": "array", "description": "One entry per field that failed validation.", "items": { "type": "object", "required": [ "pointer", "detail" ], "properties": { "pointer": { "type": "string", "description": "An [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901) JSON Pointer to the offending field in the request.", "example": "/name" }, "detail": { "type": "string", "description": "A human-readable explanation of this field's failure.", "example": "must be 100 characters or fewer" } } } } } } ] }, "Problem": { "type": "object", "description": "Problem details for an HTTP API error, as defined by [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). Served as `application/problem+json`.", "required": [ "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri-reference", "default": "https://help.awin.com/apis/error", "description": "A URI reference identifying the problem type. APIs SHOULD define a stable, dereferenceable URI per domain-specific problem type.", "example": "https://help.awin.com/apis/error" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type. Stable across occurrences; does not change from occurrence to occurrence.", "example": "Not Found" }, "status": { "type": "integer", "description": "The HTTP status code, repeated here for convenience.", "example": 404 }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence. Intended for the developer, not the end user — do not parse it.", "example": "Resource not found with that ID" }, "instance": { "type": "string", "format": "uri-reference", "description": "A URI reference identifying this specific occurrence, typically the request path.", "example": "/v1/advertisers/12345/prepayments" }, "code": { "type": "string", "description": "A stable, machine-readable error code. It does not change when `detail` is reworded, so clients branch on `code`, never on `detail`.", "enum": [ "VALIDATION_FAILED", "INVALID_SORT", "UNAUTHORIZED", "MISSING_TOKEN", "INVALID_TOKEN", "FORBIDDEN", "ACCESS_DENIED", "CLIENT_NOT_CONFIGURED", "NOT_FOUND", "METHOD_NOT_ALLOWED", "NOT_ACCEPTABLE", "CONFLICT", "CONTENT_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "BUSINESS_RULE_VIOLATION", "TOO_MANY_REQUESTS", "USER_RATE_LIMIT_EXCEEDED", "ROUTE_RATE_LIMIT_EXCEEDED", "LINK_SHORTENER_QUOTA_EXCEEDED", "INTERNAL_ERROR", "BAD_GATEWAY", "SERVICE_UNAVAILABLE", "DEPENDENCY_UNAVAILABLE", "GATEWAY_TIMEOUT", "FEATURE_NOT_ENABLED", "ACCOUNT_IN_DEBT", "DUPLICATE_ENQUIRY_ID", "TRANSACTION_QUERY_NOT_PENDING", "MEMBERSHIP_INACTIVE", "ORDER_REF_ALREADY_TRACKED", "ORDER_REF_ALREADY_QUERIED", "TRANSACTION_DATE_BEFORE_ADVERTISER_LIVE_DATE", "CURRENCY_NOT_SUPPORTED", "CURRENCY_MISMATCH", "TRANSACTION_DATE_IN_FUTURE", "TRANSACTION_DATE_TOO_OLD", "OVERRIDE_NOT_ALLOWED" ], "example": "NOT_FOUND" } } } }, "headers": { "RateLimitLimit": { "description": "Maximum number of requests you can make in a burst under your own rate limit. Absent when the request did not count against your own limit.", "schema": { "type": "integer", "minimum": 1, "example": 5 } }, "RateLimitRemaining": { "description": "Number of requests you have left under your own rate limit. Absent when the request did not count against your own limit.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, "RateLimitReset": { "description": "Number of seconds until your own rate limit is fully restored. Absent when the request did not count against your own limit.", "schema": { "type": "integer", "minimum": 0, "example": 1 } }, "RetryAfter": { "description": "Number of seconds to wait before retrying the request.", "required": true, "schema": { "type": "integer", "minimum": 0, "example": 1 } } }, "responses": { "Unauthorized": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://help.awin.com/apis/error", "title": "Unauthorized", "status": 401, "detail": "No valid credentials were supplied with the request", "code": "UNAUTHORIZED" } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://help.awin.com/apis/error", "title": "Forbidden", "status": 403, "detail": "You do not have the correct privileges to access this resource", "code": "FORBIDDEN" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "NotFound": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://help.awin.com/apis/error", "title": "Not Found", "status": 404, "detail": "Resource not found with that ID", "code": "NOT_FOUND" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "UnsupportedMediaType": { "description": "Unsupported Media Type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://help.awin.com/apis/error", "title": "Unsupported Media Type", "status": 415, "detail": "Content-Type must be application/json", "code": "UNSUPPORTED_MEDIA_TYPE" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "TooManyRequests": { "description": "Too Many Requests", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "userRateLimitExceeded": { "value": { "type": "https://help.awin.com/apis/error", "title": "User rate limit exceeded", "status": 429, "detail": "You have exceeded your rate limit across the public API. Retry after the number of seconds in the Retry-After header", "code": "USER_RATE_LIMIT_EXCEEDED" } }, "routeRateLimitExceeded": { "value": { "type": "https://help.awin.com/apis/error", "title": "Route rate limit exceeded", "status": 429, "detail": "This endpoint is receiving more requests than it can accept right now. Retry after the number of seconds in the Retry-After header", "code": "ROUTE_RATE_LIMIT_EXCEEDED" } }, "tooManyRequests": { "value": { "type": "https://help.awin.com/apis/error", "title": "Too Many Requests", "status": 429, "detail": "Rate limit exceeded", "code": "TOO_MANY_REQUESTS" } } } } } }, "ServiceUnavailable": { "description": "Service Unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://help.awin.com/apis/error", "title": "Service Unavailable", "status": 503, "detail": "The service is temporarily unavailable", "code": "SERVICE_UNAVAILABLE" } } } }, "UnexpectedError": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://help.awin.com/apis/error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred", "code": "INTERNAL_ERROR" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } }, "securitySchemes": { "patBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Personal Access Token, sent as `Authorization: Bearer `." } } } } ````