Fathom AnalyticsAPI

Command Palette

Search for a command to run...

v1

Events

Create and manage events (goals) for a site.

List events#

GEThttps://api.usefathom.com/v1/sites/{site_id}/events

Permissions: Requires read access to the site (all-sites-readonly, read:{site_id} or manage:{site_id}).

Return a list of all events this site owns. Events are sorted by created_at ascending to allow you to paginate with ease.

The currency field is only populated on Create and Update responses; it is returned as null on list and get responses.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Query parameters

limitintegeroptional
A limit on the number of objects to be returned, between 1 and 100.
Default: 10
starting_afterstringoptional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For example, if you make a list request and receive 10 objects ending with obj_foo, your subsequent call can include starting_after=obj_foo to fetch the next page.
ending_beforestringoptional
A cursor for use in pagination, working in the opposite direction to starting_after. ending_before is an object ID that defines your place in the list.

Returns

A list of event objects.

GET
curl "https://api.usefathom.com/v1/sites/CDBUGS/events" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "object": "list",
    "url": "/v1/sites/CDBUGS/events",
    "has_more": false,
    "data": [
        {
            "id": "ABCDEFGH",
            "object": "event",
            "name": "Signed up to newsletter",
            "currency": null,
            "created_at": "2020-08-21 15:24:00"
        },
        {
            "id": "IJKLMNOP",
            "object": "event",
            "name": "Purchased product",
            "currency": null,
            "created_at": "2020-08-21 15:24:00"
        }
    ]
}

Get event#

GEThttps://api.usefathom.com/v1/sites/{site_id}/events/{event_id}

Permissions: Requires read access to the site (all-sites-readonly, read:{site_id} or manage:{site_id}).

Return a single event.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event, as returned when the event was created.
Example: ABCDEFGH

Returns

An event object.

GET
curl "https://api.usefathom.com/v1/sites/CDBUGS/events/ABCDEFGH" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "id": "ABCDEFGH",
    "object": "event",
    "name": "Signed up to newsletter",
    "currency": null,
    "created_at": "2020-08-21 15:24:00"
}

Create event#

POSThttps://api.usefathom.com/v1/sites/{site_id}/events

Permissions: Requires write access to the site (manage:{site_id}).

Create an event.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS

Body parameters

namestringrequired
The name of the event (up to 255 characters).
Example: Purchase early access
currencystringoptional
The currency used for any value attached to this event's completions. If omitted, defaults to dollar.
Default: dollarOptions:dollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

Returns

An event object.

POST
curl -X POST "https://api.usefathom.com/v1/sites/CDBUGS/events" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Purchase early access"
  }'
Response
{
    "id": "ABCDEFGH",
    "object": "event",
    "name": "Purchase early access",
    "currency": "dollar",
    "created_at": "2021-08-10 10:45:43"
}

Update event#

POSThttps://api.usefathom.com/v1/sites/{site_id}/events/{event_id}

Permissions: Requires write access to the site (manage:{site_id}).

Update an event. Send only the fields you want to change.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event you wish to update.
Example: ABCDEFGH

Body parameters

namestringoptional
The name of the event (up to 255 characters).
currencystringoptional
The currency used for any value attached to this event's completions.
Options:dollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

Returns

An event object.

POST
curl -X POST "https://api.usefathom.com/v1/sites/CDBUGS/events/ABCDEFGH" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "id": "ABCDEFGH",
    "object": "event",
    "name": "Purchase early access (live)",
    "currency": "dollar",
    "created_at": "2021-08-10 10:45:43"
}

Wipe event#

Deprecated
DELETEhttps://api.usefathom.com/v1/sites/{site_id}/events/{event_id}/data

This endpoint is no longer available

This endpoint has been retired and now returns 410 Gone. It is no longer possible to wipe an event's completion data via the API.

Previously wiped all completion data belonging to an event. This endpoint is no longer available.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event.

Delete event#

DELETEhttps://api.usefathom.com/v1/sites/{site_id}/events/{event_id}

Permissions: Requires write access to the site (manage:{site_id}).

Delete an event. Careful — you can't undo this, and neither can we.

Path parameters

site_idstringrequired
The ID of the site. This is the same string you use in your tracking code.
Example: CDBUGS
event_idstringrequired
The id (tracking code) of the event you wish to delete.

Returns

Returns a deleted object on success. Otherwise, this call returns an error.

DELETE
curl -X DELETE "https://api.usefathom.com/v1/sites/CDBUGS/events/ABCDEFGH" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
Response
{
    "id": "ABCDEFGH",
    "object": "event",
    "deleted": true
}