Click events for a link

Overview

Get the individual click events on a tracked link: when, from where.

Use this for detailed click analysis.

You'll need the link id (id from Email links clicked or Text links clicked). Events are listed from the day the link was created unless you send a window (start_date, end_date).

Returns the events, newest first, 20 per page unless you set limit.

Prerequisites

A bearer token. See Authentication.
The link's id (click_url_id).

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/campaign/click-url/{click_url_id}/events

Authentication

Account token

The link must belong to a campaign of the caller's own company. Any other id returns 404 Click URL not found.

Rate limit

120 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

Parameter	In	Type	Required	Description
`click_url_id`	path	integer	Yes	The tracked link's id (digits only).
`start_date`	query	string	No	Start of the window, `Y-m-d`. Default: the day the link was created. If it's after `end_date`, the two are swapped.
`end_date`	query	string	No	End of the window, `Y-m-d`. Default: today.
`page`	query	integer	No	Page number, from 1. Default 1.
`limit`	query	integer	No	Events per page, 10 to 100. Values below 10 are raised to 10; above 100 returns `422`. Default 20.

Request body

None.

Request payload

None.

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`data`	object	The page of events.
`data.current_page`	integer	This page's number.
`data.per_page`	integer	Events per page (`limit`).
`data.total`	integer	Events across all pages.
`data.last_page`	integer	Number of the last page.
`data.click_url`	object	The tracked link.
`data.click_url.id`	integer	The link's id.
`data.click_url.name`	string	The link's name.
`data.click_url.placeholder`	string	The template placeholder for the link.
`data.click_url.url`	string or null	Where the link goes.
`data.click_url.channel_type`	string	`email` or `sms`.
`data.events[]`	array of objects	The clicks, newest first.
`data.events[].id`	integer	The event's id.
`data.events[].event`	string	Always `click`.
`data.events[].ip`	string	IP address of the click.
`data.events[].user_agent`	string	Browser user agent of the click.
`data.events[].referer`	string or null	Referring page, when the browser sent one.
`data.events[].metadata`	object or null	Extra details stored with the click.
`data.events[].created_at`	string	When the click happened (ISO 8601).
`data.events[].customer_data`	object	The request that was clicked: with `email` for an email, with `phone_number` for a text. Left out when the click isn't tied to a request.
`data.events[].customer_data.id`	integer	The email or text request's id.
`data.events[].customer_data.email`	string	The recipient's email address (email requests).
`data.events[].customer_data.phone_number`	string	The recipient's phone number (text requests).
`data.events[].customer_data.status`	string	The request's status.
`data.events[].customer_data.sent_at`	string or null	When the request was sent (ISO 8601).
`data.events[].customer_data.customer_name`	string or null	The customer's name.
`data.events[].customer_data.requestor_name`	string or null	Name of the person who asked for the review.

Response payload

{
  "data": {
    "status": "success",
    "data": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "last_page": 8,
      "click_url": {
        "id": 45,
        "name": "Direct to Manager",
        "placeholder": "directTo_manager",
        "url": "https://example.com/manager",
        "channel_type": "email"
      },
      "events": [
        {
          "id": 123,
          "event": "click",
          "ip": "192.168.1.1",
          "user_agent": "Mozilla/5.0...",
          "referer": "https://gmail.com",
          "metadata": null,
          "created_at": "2026-06-15T10:30:00.000Z",
          "customer_data": {
            "id": 88,
            "email": "[email protected]",
            "status": "clicked",
            "sent_at": "2026-06-15T09:00:00.000Z",
            "customer_name": "Jane Smith",
            "requestor_name": "Front Desk"
          }
        }
      ]
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

404 Click URL not found

{
  "message": "Click URL not found",
  "status": "error",
  "errors": []
}

422 Date not in Y-m-d

{
  "message": "The start date field must match the format Y-m-d.",
  "errors": {
    "start_date": [
      "The start date field must match the format Y-m-d."
    ]
  }
}

422 limit above 100

{
  "message": "The limit field must not be greater than 100.",
  "errors": {
    "limit": [
      "The limit field must not be greater than 100."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	One page of click events.
`401`	The token is missing, expired or invalid.
`404`	No tracked link with that id in your company (`Click URL not found`).
`422`	A date isn't `Y-m-d`, or `limit` is above 100.
`429`	More than 120 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/click-url/45/events?page=1&limit=20" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'