Browse API documentation
API documentation

Events

Manage events for a site.

Search API documentation
    v1

    List events#

    GET/sites/{site_id}/events

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

    The id field is going away

    Each event still returns an id (the old goal code). We are removing that field on 24 September 2026. Identify events by name instead.
    The currency field is returned as null on list responses. Set it with Set event currency.

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

    Set event currency#

    POST/sites/{site_id}/events/currency

    Set the currency of an event by its name. Use this instead of updating an event by its goal code. If more than one event row shares the name, they are treated as one event and every matching row is updated.

    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
    currencystringrequired
    The currency used for any value attached to this event's completions.
    Options:dollarpoundeuroyuanpesoshekelyenwonhryvniafrancrupeeintegernone

    Returns

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

    POST
    curl -X POST "https://api.usefathom.com/v1/sites/CDBUGS/events/currency" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Purchase early access",
    "currency": "pound"
  }'
    Response
    {
    "object": "event",
    "name": "Purchase early access",
    "currency": "pound",
    "updated": true
}

    Delete event#

    DELETE/sites/{site_id}/events

    Delete an event by its name. If more than one event row shares the name, they are treated as one event and every matching row is deleted.

    Path parameters

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

    Query parameters

    namestringrequired
    The name of the event you wish to delete.
    Example: Purchase early access

    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?name=Purchase%20early%20access" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
    Response
    {
    "object": "event",
    "name": "Purchase early access",
    "deleted": true
}

    Get event#

    Deprecated

    GET/sites/{site_id}/events/{event_id}

    This endpoint is no longer available

    This endpoint is no longer available. Use List events.

    Previously returned a single event by its goal code. 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, as returned when the event was created.
    Example: ABCDEFGH

    Create event#

    Deprecated

    POST/sites/{site_id}/events

    This endpoint is no longer available

    This endpoint is no longer available. Track the event on your site, then use List events and Set event currency.

    Previously created 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

    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

    Update event#

    Deprecated

    POST/sites/{site_id}/events/{event_id}

    This endpoint is no longer available

    This endpoint is no longer available. To change an event's currency, use Set event currency.

    Previously updated an event by its goal code. 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 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

    Wipe event#

    Deprecated

    DELETE/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#

    Deprecated

    DELETE/sites/{site_id}/events/{event_id}

    This endpoint is no longer available

    This endpoint is no longer available. To delete an event, use Delete event with the event name.

    Previously deleted an event by its goal code. 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 you wish to delete.