Link Builder API Documentation

Q: How do I add a custom tracking code to a generated link?

Include the optional custom_code parameter in your POST request body. This sets the clickref or sub-ID for the generated link. The custom code must be 50 characters or fewer.

Overview

The Link Builder API generates affiliate tracking links for any destination URL. POST a URL and the API automatically detects the advertiser and network, then returns a ready-to-use affiliate link. This powers the Hi Energy Chrome extension and can be used by any authorized client.

Key Features

Multi-network – Supports Awin, CJ, Impact, Rakuten, Partnerize, Pepperjam, and Avantlink.
Auto-detection – Automatically identifies the advertiser and network from the URL domain.
Custom tracking – Optional custom_code parameter for clickref/sub-ID tracking.
Feature-gated – Requires link_generator_enabled on your publisher (or admin access).
Rate limited – Standard API rate limits apply.

Endpoint

Generate tracking link

POST /api/v1/deeplinks/generate

Generates an affiliate tracking link for the given URL. Returns the tracking URL, network, and advertiser name.

Authentication

X-Api-Key: YOUR_API_KEY

Sign in to get your API key.

Authorization

This endpoint has additional access controls beyond API key authentication:

User Type	Access	Requirement
Admin	Allowed	No additional requirements
Paid Publisher	Allowed	`link_generator_enabled` must be `true` on publisher record
Free User	Denied	Returns 403 Forbidden
Paid (feature disabled)	Denied	Returns 403 Forbidden

Check the link_generator_enabled field in the /api_key response to determine whether the current user has access before calling this endpoint.

API Playground

This endpoint uses POST, so the playground below shows sample curl commands. Sign in to enable live testing with your API key.

Action	Method	Endpoint	Description
Generate tracking link	`POST`	`/api/v1/deeplinks/generate`	POST with url param. Response JSON includes deeplink, network, advertiser_name.
With custom code	`POST`	`/api/v1/deeplinks/generate`	Include custom_code param for clickref/sub-ID tracking.

Generate a tracking link

curl -X POST "https://app.hienergy.ai/api/v1/deeplinks/generate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d "url=https://www.example-merchant.com/product/123"

Generate with custom tracking code

curl -X POST "https://app.hienergy.ai/api/v1/deeplinks/generate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d "url=https://www.example-merchant.com/sale" \
  -d "custom_code=spring_campaign"

Parameters

Send parameters as form data or JSON in the POST request body.

Parameter	Type	Required	Description
`url`	string	Yes	The destination URL to generate an affiliate tracking link for. Must be a valid URL with a domain matching an advertiser in your catalog.
`custom_code`	string	No	Custom tracking code (clickref/sub-ID) to embed in the generated link. Maximum 50 characters.

Response Format

Success (200 OK)

{
  "deeplink": "https://www.awin1.com/cread.php?awinmid=12345&awinaffid=99999&ued=https%3A%2F%2Fwww.example-merchant.com%2Fproduct%2F123",
  "network": "awin",
  "advertiser_name": "Example Merchant"
}

Field	Type	Description
`deeplink`	string	The generated affiliate tracking URL (JSON field name remains `deeplink`), ready to use.
`network`	string	The affiliate network used (e.g. `awin`, `cj`, `impact`, `rakuten`).
`advertiser_name`	string	The matched advertiser's name.

Error Handling

All errors follow the standard Hi Energy API error format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

HTTP Status	Error Code	Description
`400`	`MISSING_PARAMETER`	The `url` parameter is missing or blank.
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`403`	`FORBIDDEN`	Link generator is not enabled for your account (free user or feature disabled).
`422`	`INVALID_PARAMETERS`	Custom code exceeds 50 characters.
`422`	`GENERATION_FAILED`	Could not generate a tracking link. Domain may be unrecognized, ignored (Amazon/eBay), or the network API call failed.
`429`	`RATE_LIMITED`	Rate limit exceeded. Check `Retry-After` header.

Frequently Asked Questions

The Link Builder API lets you generate affiliate tracking links for any URL. POST a destination URL to /api/v1/deeplinks/generate and receive an affiliate tracking link for the matching advertiser and network. Supports Awin, CJ, Impact, Rakuten, Partnerize, Pepperjam, and Avantlink.

The Link Builder API requires a paid publisher account with the link_generator_enabled feature flag turned on, or admin access. Free users and publishers without the feature enabled will receive a 403 Forbidden response. Check the link_generator_enabled field in the /api_key response to see if your account has access.

Include the optional custom_code parameter in your POST request body. This sets the clickref or sub-ID for the generated link, allowing you to track campaigns and sources. The custom code must be 50 characters or fewer.

If the domain doesn't match any advertiser in your publisher's catalog, you'll receive a 422 Unprocessable Entity error with code GENERATION_FAILED. Amazon and eBay domains are explicitly ignored and return a specific error message explaining that these networks are not supported.

The Link Builder API supports generating links for Awin, CJ (Commission Junction), Impact, Rakuten, Partnerize, Pepperjam, and Avantlink. The network is automatically detected based on the advertiser matched to the URL domain.