Link Shortening and Click Tracking API

Users has option to programmatically interact with the refer.is 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.

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

API Key is required for all requests. Every workspace has it's 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:

Authentication: 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"
  }'

Response

{
  "data": {
    "id": "92fc175e-2508-458d-b490-5c78675c8e6b",
    "slug": "abc",
    "link": "https://refer.is/abc",
    "url": "https://google.com",
  }
}

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

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

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' \
  -H "Authorization: Bearer <API_KEY>"

Parameters

Response

Response is a PNG image.

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

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

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

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

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