Link Shortening and Click Tracking API

You can interact with refer.is programmatically through its API. The API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Need help? Contact us through the support widget in the bottom right corner of the page. We are happy to help.

OpenAPI

API documentation is available in the OpenAPI specification format. You can find the OpenAPI specification file here.

Authentication

An API key is required for all requests. Every workspace has its own API key. You can find your API key in the settings page of your workspace under the "API key" section.

To authenticate your requests include the following header:

Authorization: Bearer <API_KEY>

Get Me

Get information about your workspace.

Request

curl -X GET 'https://api.refer.is/v1/me' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>"

Response

{
  "data": {
    "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "name": "Workspace name"
  }
}

List Domains

List domains usable in your workspace (your own plus shared system domains).

Request

curl -X GET 'https://api.refer.is/v1/domains' \
  -H "Authorization: Bearer <API_KEY>"

Parameters

Parameter	Required	Description
`page`	No	Page number (default 1).
`limit`	No	Items per page, up to 100 (default 10).

Response

{
  "data": [
    {
      "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
      "name": "refer.is",
      "status": "connected"
    }
  ],
  "meta": {
    "limit": 10,
    "total": 1,
    "page": 1
  }
}

Get Domain

Get a domain in your workspace, including its verification status.

Request

curl -X GET 'https://api.refer.is/v1/domains/92fc175e-2508-458d-b490-5c78675c8e6b' \
  -H "Authorization: Bearer <API_KEY>"

Response

{
  "data": {
    "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "name": "refer.is",
    "status": "connected"
  }
}

Create Domain

Connect a custom domain to your workspace. Verify it afterwards in the workspace settings.

Request

curl -X POST 'https://api.refer.is/v1/domains' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "name": "go.example.com",
    "url": "https://example.com"
  }'

Parameters

Parameter	Required	Description
`name`	Yes	Domain hostname, e.g. go.example.com
`url`	Yes	Fallback redirect URL for direct domain visits

Response

Returns 201 Created.

{
  "data": {
    "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "name": "go.example.com",
    "status": "disconnected"
  }
}

Delete Domain

Remove a custom domain from your workspace. Shared system domains cannot be removed.

Request

curl -X DELETE 'https://api.refer.is/v1/domains/92fc175e-2508-458d-b490-5c78675c8e6b' \
  -H "Authorization: Bearer <API_KEY>"

Response

Returns 204 No Content with an empty body.

Create Link

Create new link in your workspace. List usable domain IDs via List Domains first.

Request

curl -X POST 'https://api.refer.is/v1/links' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "url":"https://google.com",
    "domain_id": "<DOMAIN_ID>"
  }'

Parameters

Parameter	Required	Description
`url`	Yes	Destination URL the short link redirects to
`domain_id`	Yes	Domain ID from List Domains
`slug`	No	Custom back-half of the link. A random 8-character slug is generated when omitted

Response

Returns 201 Created.

{
  "data": {
    "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "slug": "abc",
    "link": "https://refer.is/abc",
    "url": "https://google.com",
    "domain_id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

List Links

List links in your workspace.

Request

curl -X GET 'https://api.refer.is/v1/links?query=google&page=1' \
  -H "Authorization: Bearer <API_KEY>"

Parameters

Parameter	Required	Description
`query`	No	Search slugs and destination URLs
`page`	No	Page number (default 1).
`limit`	No	Items per page, up to 100 (default 10).

Response

{
  "data": [
    {
      "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
      "slug": "abc",
      "link": "https://refer.is/abc",
      "url": "https://google.com",
      "domain_id": "92fc175e-2508-458d-b490-5c78675c8e6b",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 10,
    "total": 1,
    "page": 1
  }
}

Get Link

Get existing link from your workspace.

Request

curl -X GET 'https://api.refer.is/v1/links/92fc175e-2508-458d-b490-5c78675c8e6b' \
  -H "Authorization: Bearer <API_KEY>"

Response

{
  "data": {
    "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "slug": "abc",
    "link": "https://refer.is/abc",
    "url": "https://google.com",
    "domain_id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

Update Link

Update the destination URL of an existing link. The id, slug, and stats stay intact.

Request

curl -X PATCH 'https://api.refer.is/v1/links/92fc175e-2508-458d-b490-5c78675c8e6b' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "url":"https://example.com"
  }'

Parameters

Parameter	Required	Description
`url`	Yes	New destination URL the short link redirects to

Response

{
  "data": {
    "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "slug": "abc",
    "link": "https://refer.is/abc",
    "url": "https://example.com",
    "domain_id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

Delete Link

Delete existing link from your workspace.

Request

curl -X DELETE 'https://api.refer.is/v1/links/92fc175e-2508-458d-b490-5c78675c8e6b' \
  -H "Authorization: Bearer <API_KEY>"

Response

Returns 204 No Content with an empty body.

Get QR Code

Get QR code for a link. Public — no API key required, the code encodes the public short URL.

Request

curl -X GET 'https://api.refer.is/v1/links/92fc175e-2508-458d-b490-5c78675c8e6b/qr?background_color=%23ffffff&dot_color=%23000000'

Parameters

Parameter	Required	Description
`background_color`	No	Background color as a 6-digit hex, e.g. `#ffffff` (URL-encoded as `%23ffffff`)
`dot_color`	No	Dot color as a 6-digit hex, e.g. `#000000`

Response

Returns an SVG image (image/svg+xml).

Please note that the QR code is generated on the fly and the endpoint is rate limited. If you need to use the same QR code multiple times you should download it and cache it on your server.

Get Browsers Analytics

Get click analytics for browsers.

Request

curl -X GET 'https://api.refer.is/v1/analytics/browsers?start=2024-01-01T00:00:00Z&end=2024-01-31T00:00:00Z' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>"

Parameters

Parameter	Required	Description
`start`	Yes	ISO 8601
`end`	Yes	ISO 8601
`page`	No	Page number (default 1).
`limit`	No	Items per page, up to 100 (default 10).
`link_id`	No	Scope to a single link ID
`domain_id`	No	Scope to a single domain ID

Response

{
  "data": [
    {
      "value": "chrome",
      "count": 100
    },
    {
      "value": "safari",
      "count": 50
    }
  ],
  "meta": {
    "limit": 10,
    "total": 2,
    "page": 1
  }
}

Get Countries Analytics

Get click analytics for countries.

Request

curl -X GET 'https://api.refer.is/v1/analytics/countries?start=2024-01-01T00:00:00Z&end=2024-01-31T00:00:00Z' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>"

Parameters

Parameter	Required	Description
`start`	Yes	ISO 8601
`end`	Yes	ISO 8601
`page`	No	Page number (default 1).
`limit`	No	Items per page, up to 100 (default 10).
`link_id`	No	Scope to a single link ID
`domain_id`	No	Scope to a single domain ID

Response

{
  "data": [
    {
      "value": "US",
      "count": 100
    },
    {
      "value": "CA",
      "count": 50
    }
  ],
  "meta": {
    "limit": 10,
    "total": 2,
    "page": 1
  }
}

Get Referrers Analytics

Get click analytics for referrers.

Request

curl -X GET 'https://api.refer.is/v1/analytics/referrers?start=2024-01-01T00:00:00Z&end=2024-01-31T00:00:00Z' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>"

Parameters

Parameter	Required	Description
`start`	Yes	ISO 8601
`end`	Yes	ISO 8601
`page`	No	Page number (default 1).
`limit`	No	Items per page, up to 100 (default 10).
`link_id`	No	Scope to a single link ID
`domain_id`	No	Scope to a single domain ID

Response

{
  "data": [
    {
      "value": "https://m.facebook.com",
      "count": 50
    },
    {
      "value": "https://x.com",
      "count": 50
    },
    {
      "value": null,
      "count": 50
    }
  ],
  "meta": {
    "limit": 10,
    "total": 3,
    "page": 1
  }
}

Get URLs Analytics

Get click analytics for urls.

Request

curl -X GET 'https://api.refer.is/v1/analytics/urls?start=2024-01-01T00:00:00Z&end=2024-01-31T00:00:00Z' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>"

Parameters

Parameter	Required	Description
`start`	Yes	ISO 8601
`end`	Yes	ISO 8601
`page`	No	Page number (default 1).
`limit`	No	Items per page, up to 100 (default 10).
`link_id`	No	Scope to a single link ID
`domain_id`	No	Scope to a single domain ID

Response

{
  "data": [
    {
      "value": "https://refer.is",
      "count": 20
    },
    {
      "value": "https://refer.is/docs",
      "count": 10
    },
    {
      "value": "https://refer.is/pricing",
      "count": 5
    }
  ],
  "meta": {
    "limit": 10,
    "total": 3,
    "page": 1
  }
}

OpenAPI

Authentication

Get Me

Request

Response

List Domains

Request

Parameters

Response

Get Domain

Request

Response

Create Domain

Request

Parameters

Response

Delete Domain

Request

Response

Create Link

Request

Parameters

Response

List Links

Request

Parameters

Response

Get Link

Request

Response

Update Link

Request

Parameters

Response

Delete Link

Request

Response

Get QR Code

Request

Parameters

Response

Get Browsers Analytics

Request

Parameters

Response

Get Countries Analytics

Request

Parameters

Response

Get Referrers Analytics

Request

Parameters

Response

Get URLs Analytics

Request

Parameters

Response

Start creating branded links today