---
title: "Bind a link to a template"
method: POST
path: "/urls/{code}/binding"
tags: ["Bindings"]
---

# Bind a link to a template

`POST /urls/{code}/binding`

## Request

- Base URL: `https://gajo.io/api/v1`
- URL: `https://gajo.io/api/v1/urls/{code}/binding`
- Auth: API key in header `x-api-key`

**Requires a Pro plan.** Attaches one route template (`templateType: Device`) or A/B template (`templateType: AbTest`) to the link and supplies a concrete destination for each slot. A link has at most one binding; binding again replaces it. Device bindings need an endpoint for every slot in the route template, unless a `Default` endpoint is included. A/B bindings need an endpoint for every variant. Endpoint `targetUrl`s may be app deep links (custom schemes) with a web `fallbackUrl`, such as the App Store or Google Play listing, used when the app is not installed. Takes effect immediately.

## Request body

- BindRequest
  - `templateType` 'Device' | 'AbTest', required: `Device` routes by device class; `AbTest` splits traffic by percentage.
  - `templateName` string, required: Name of your route template or A/B template.
  - `endpoints` BindingEndpoint[], required: One endpoint per slot. Device bindings must cover every template slot unless a `Default` endpoint is included; A/B bindings must cover every variant, plus `Variant:Device` endpoints for any variant that chains to a route template.
    - `slotKey` union, required: For `Device` bindings, one of the template's device slots. For `AbTest` bindings, one of the template's variant names, or `Variant:Device` (e.g. `Control:IOS`) for the device destinations of a variant that chains to a route template.
      - 'Android' | 'IOS' | 'Mobile' | 'Tablet' | 'Desktop' | 'Default': Device slot used by route templates and Device bindings. At redirect time OS-specific slots (`Android`, `IOS`) are matched first, then device classes (`Mobile`, `Tablet`, `Desktop`), then `Default` catches everything else.
      - string: A/B variant name
    - `targetType` 'Url' | 'RouteTemplate': `Url` (default) sends the slot to `targetUrl`. `RouteTemplate` is reserved for chaining an A/B variant to a route template; this is not fully supported yet, so use `Url` targets.
    - `targetUrl` string: Required when `targetType` is `Url`. May be an app deep link (custom scheme).
    - `fallbackUrl` string: Only when `targetUrl` is an app deep link: web URL (e.g. App Store / Google Play listing) used when the app is not installed.
    - `routeTemplateName` string: With `targetType: RouteTemplate` (A/B bindings): the route template this variant chains to. Add the variant's per-device destinations as endpoints keyed `Variant:Device`, covering every slot of the route template or including `Variant:Default`.
    - `endpointName` string: Optional label for this endpoint.
  - `flowJson` string, nullable: Optional layout state for the dashboard's visual Route Builder. API clients can omit it.

## Response `200`

The new binding.

- BindingCreatedResult: Envelope shared by every response.
  - `success` true, required: `true` when the request succeeded.
  - `message` string, nullable: Human-readable status or error message. Often `null` on reads.
  - `data` object, required: Operation-specific payload; `null` or absent when there is nothing to return.
    - `shortCode` string, required
    - `routingType` 'Device' | 'AbTest', required: `Device` routes by device class; `AbTest` splits traffic by percentage.
    - `templateName` string, required
    - `endpoints` Endpoint[], required
      - `slotKey` string, required: Device slot (Device bindings) or variant name (A/B bindings).
      - `targetType` 'Url' | 'RouteTemplate', required: `Url` (default) sends the slot to `targetUrl`. `RouteTemplate` is reserved for chaining an A/B variant to a route template; this is not fully supported yet, so use `Url` targets.
      - `targetUrl` string, nullable, required
      - `fallbackUrl` string, nullable, required: Web fallback when `targetUrl` is an app deep link and the app is not installed.
      - `routeTemplateName` string, nullable, required: Name of the chained route template when `targetType` is `RouteTemplate` (`null` otherwise, or if it was deleted).
      - `routeTemplateId` integer, nullable, required: Numeric ID of the chained route template when `targetType` is `RouteTemplate`. Deprecated: use `routeTemplateName`.
      - `endpointName` string, nullable, required: Optional label.

## Other responses

- `400`: Invalid request. `message` explains what to fix.
- `401`: The `x-api-key` header is missing, or the key is unknown or revoked.
- `403`: Your plan is not Pro (the message names the Pro feature).
- `404`: No link with this code exists on your account.
- `429`: Per-minute rate limit exceeded. Wait `Retry-After` seconds.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/gajo/apis/gajo-api.md) · [All operations](https://skmtc.dev/gajo/apis/gajo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gajo/apis/gajo-api/revisions/de6fe920cc26?raw)