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. You can also use the OpenAPI specification file to generate client libraries for different programming languages.

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"
  }
}

Create Link

Create new link in your workspace.

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": "refer.is"
  }'

Parameters

Parameter	Required	Description
`url`	Yes	Destination URL the short link redirects to
`domain`	Yes	`refer.is` or one of your connected custom 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",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

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",
    "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 existing link from your workspace.

Request

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

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 - each page has up to 100 items.

Response

{
  "data": [
    {
      "value": "chrome",
      "count": 100
    },
    {
      "value": "safari",
      "count": 50
    }
  ],
  "meta": {
    "limit": 100,
    "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 - each page has up to 100 items.

Response

{
  "data": [
    {
      "value": "US",
      "count": 100
    },
    {
      "value": "CA",
      "count": 50
    }
  ],
  "meta": {
    "limit": 100,
    "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 - each page has up to 100 items.

Response

{
  "data": [
    {
      "value": "https://m.facebook.com",
      "count": 50
    },
    {
      "value": "https://x.com",
      "count": 50
    },
    {
      "value": null,
      "count": 50
    }
  ],
  "meta": {
    "limit": 100,
    "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 - each page has up to 100 items.

Response

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

OpenAPI

Authentication

Get Me

Request

Response

Create Link

Request

Parameters

Response

Get Link

Request

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