Ingest API

The Ingest API is used to send tracking data (visitors, users, logins, payments, custom events) to SimpleStats. Even though the composer client package is dedicated to Laravel, the API basically works with every client! So if you'd like to use the tool, even if you're not using Laravel, you may just trigger the API requests manually.

TIP

Looking to read your analytics data programmatically? Check out the Query API.

Authentication

In order to use the API, you should authenticate your request by including your API token as a bearer token value:

Authorization: Bearer API_TOKEN_HERE

TIP

You'll receive an API token after creating a new project, our you can find your existing API tokens inside the app on the project page.

Headers

Make sure you have the following content type headers are set on every request:

Accept: application/json Content-Type: application/json

URI

SimpleStats API is hosted on the following base URI:

https://simplestats.io/api/v1/

Errors

SimpleStats uses standard HTTP response codes to communicate the outcome of API requests. These codes offer immediate insight into whether a request has been successful, encountered an error, or requires additional action.

Code	Description
200	Everything is ok.
400	Valid data was given but the request has failed.
401	No valid API Key was given.
404	The request resource could not be found.
422	The payload has missing required parameters or invalid data was given.
429	Too many attempts.
500	Request failed due to an internal error in SimpleStats.
503	SimpleStats is offline for maintenance.

Rate Limit

Rate limits depend on your subscription plan and are applied per project (API token) per minute. See Plans and Limits for details.

If you exceed your rate limit, the API will return a 429 Too Many Requests response.

Endpoints

At the moment, only the create endpoints are available. But if the id already exists on our side, the record gets updated with the new data.

Create Visitor

HTTP Request

POST /api/v1/stats-visitor

Core parameters:

Key	Type	Description
time	string `required`	The time when the user has registerd. Format: `Y-m-d H:i:s P`, before or equal `now`
ip	string `nullable`	The `ip` of the user. (does not get stored)
user_agent	string `nullable`	The `user_agent` of the user. (does not get stored)
track_referer	string `nullable`	The http tracking `referer` of the user.
track_source	string `nullable`	The tracking `source` of the user.
track_medium	string `nullable`	The tracking `medium` of the user.
track_campaign	string `nullable`	The tracking `campaign` of the user.
track_term	string `nullable`	The tracking `term` of the user.
track_content	string `nullable`	The tracking `content` of the user.
page_entry	string `nullable`	The tracking `page_entry` of the user.

Optional parameters

Key	Type	Description
location_country	string `nullable`	The location `country` of the user. (If the `ip` is set, we take the country that refers to it.)
location_region	string `nullable`	The location `region` of the user. (If the `ip` is set, we take the region that refers to it.)
location_city	string `nullable`	The location `city` of the user. (If the `ip` is set, we take the city that refers to it.)
device_type	string `nullable`	The device `type` of the user. (If the `user_agent` is set, we take the device type that refers to it.)
device_platform	string `nullable`	The device `platform` (OS) of the user. (If the `user_agent` is set, we take the device platform that refers to it.)
device_browser	string `nullable`	The device `browser` of the user. (If the `user_agent` is set, we take the device browser that refers to it.)
page_entry	string `nullable`	The page `entry` point of the user.
properties	object `nullable`	Custom properties to group analytics by, as a `name: value` map (e.g. `{"ab_test": "B"}`). Values must be scalar. Max 50 names per request. See custom properties.

Payload

json

{
    "ip": "127.0.0.1",
    "user_agent": "Mozilla/5.0 (Linux; Android 13; Pixel 6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36",
    "track_source": "test",
    "time": "2024-04-04"
}

Response

json

{
    "message": "Stats Visitor Request accepted.",
    "visitor_hash": "9a7c4f2e8b1d6a3c5e0f7b2d4a8c1e6f"
}

TIP

If no visitor_hash is given, it gets generated from time, ip and user_agent. The returned visitor_hash can be used to reference this visitor in other endpoints (payments, custom events, custom properties).

Create User

HTTP Request

POST /api/v1/stats-user

Core parameters:

Key	Type	Description
id	mixed `required`	The user id.
time	string `required`	The time when the user has registerd. Format: `Y-m-d H:i:s P`, before or equal `now`
ip	string `nullable`	The `ip` of the user. (does not get stored)
user_agent	string `nullable`	The `user_agent` of the user. (does not get stored)
track_referer	string `nullable`	The http tracking `referer` of the user.
track_source	string `nullable`	The tracking `source` of the user.
track_medium	string `nullable`	The tracking `medium` of the user.
track_campaign	string `nullable`	The tracking `campaign` of the user.
track_term	string `nullable`	The tracking `term` of the user.
track_content	string `nullable`	The tracking `content` of the user.
page_entry	string `nullable`	The tracking `page_entry` of the user.

Optional parameters

Key	Type	Description
location_country	string `nullable`	The location `country` of the user. (If the `ip` is set, we take the country that refers to it.)
location_region	string `nullable`	The location `region` of the user. (If the `ip` is set, we take the region that refers to it.)
location_city	string `nullable`	The location `city` of the user. (If the `ip` is set, we take the city that refers to it.)
device_type	string `nullable`	The device `type` of the user. (If the `user_agent` is set, we take the device type that refers to it.)
device_platform	string `nullable`	The device `platform` (OS) of the user. (If the `user_agent` is set, we take the device platform that refers to it.)
device_browser	string `nullable`	The device `browser` of the user. (If the `user_agent` is set, we take the device browser that refers to it.)
page_entry	string `nullable`	The page `entry` point of the user.
visitor_hash	string `nullable`	The `visitor_hash` of the visitor this registration converted from. Links the user to its prior visit (for visit-to-registration timing).
properties	object `nullable`	Custom properties to group analytics by, as a `name: value` map (e.g. `{"ab_test": "B"}`). Values must be scalar. Max 50 names per request. See custom properties.

Payload

json

{
    "id": 1,
    "track_source": "test",
    "time": "2024-04-04"
}

Response

json

{
    "message": "Stats User Request accepted.",
    "id": 1
}

HTTP Request

POST /api/v1/stats-login

Parameters

Key	Type	Description
stats_user_id	integer `required`	The id of the user trying to login.
time	string `required`	The time when the user tries to login. Format: `Y-m-d H:i:s P`, before or equal `now`

Payload

json

{
    "stats_user_id": 1,
    "time": "2024-04-04"
}

Response

json

{
    "message": "Stats Login Request accepted.",
    "id": 1
}

Create Payment

HTTP Request

POST /api/v1/stats-payment

Parameters

Key	Type	Description
id	mixed `required`	The payment id.
stats_user_id	integer `required`	The user id associated with the payment.
visitor_hash	string `nullable`	The visitor hash.
time	string `required`	The time when the payment happened. Format: `Y-m-d H:i:s P`, before or equal `now`
gross	numeric `required`	The gross amount of the payment in cents. (e.g.: $1 = 100 Cent)
net	numeric `required`	The net amount of the payment in cents. (e.g.: $1 = 100 Cent).
currency	string `required`	The ISO-4217 currency code of the payment. (e.g.: EUR, USD, GBP ...)
subscription_interval	string `nullable`	The billing interval for subscription payments: `month` or `year`. Omit or `null` for one-time payments.
subscription_plan	string `nullable`	The subscription plan the payment belongs to (free-form, e.g. `Starter`, `Business`). Omit or `null` for one-time payments.

Payload

json

{
    "id": "1",
    "stats_user_id": "1",
    "gross": 2000,
    "net": 1800,
    "currency": "EUR",
    "subscription_interval": "month",
    "subscription_plan": "Business",
    "time": "2024-04-04"
}

Response

json

{
    "message": "Stats Payment Request accepted.",
    "id": "1"
}

Create Custom Event

HTTP Request

POST /api/v1/stats-custom-event

Parameters

Key	Type	Description
id	mixed `required`	A unique identifier for this event.
name	string `required`	The event name (e.g. "Button Clicked"). Events with the same name are grouped.
stats_user_id	mixed `nullable`	The user id associated with the event.
visitor_hash	string `nullable`	The visitor hash.
time	string `required`	The time when the event happened. Format: `Y-m-d H:i:s P`, before or equal `now`

Payload

json

{
    "id": "evt-550e8400-e29b-41d4-a716-446655440000",
    "name": "Plan Upgraded",
    "stats_user_id": "1",
    "time": "2025-04-04"
}

Response

json

{
    "message": "Stats Custom Event Request accepted.",
    "id": "evt-550e8400-e29b-41d4-a716-446655440000"
}

Create Custom Property

HTTP Request

POST /api/v1/stats-custom-properties

Parameters

Key	Type	Description
properties	object `required`	Custom properties to group analytics by, as a `name: value` map (e.g. `{"ab_test": "B"}`). Values must be scalar. Max 50 names per request.
stats_user_id	mixed `nullable`	The user id to attach the properties to. Required without `visitor_hash`.
visitor_hash	string `nullable`	The visitor hash to attach the properties to. Required without `stats_user_id`.
time	string `required`	The time the properties were current. Format: `Y-m-d H:i:s P`, before or equal `now`

Payload

json

{
    "stats_user_id": "1",
    "properties": {
        "ab_test": "B"
    },
    "time": "2026-04-04"
}

Response

json

{
    "message": "Stats Custom Property Request accepted.",
    "id": "1"
}

Ingest API ​

Authentication ​

Headers ​

URI ​

Errors ​

Rate Limit ​

Endpoints ​

Create Visitor ​

Create User ​

Create Login ​

Create Payment ​

Create Custom Event ​

Create Custom Property ​

Ingest API

Authentication

Headers

URI

Errors

Rate Limit

Endpoints

Create Visitor

Create User

Create Login

Create Payment

Create Custom Event

Create Custom Property