Skip to content

User profile

Get profile

GET/user/profile

Used to get the caller's profile, message balances and the time range covered by their device history.

Request

Auth: api_key

Request body:

None

Request example:

https://spoilerinterface.com/interface/user/profile?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Response

{
    "success": {
        "user_id": 301659085216623,
        "username": "user@example.com",
        "email": "user@example.com",
        "firstname": "John",
        "surname": "Doe",
        "gender": "M",
        "date_of_birth": "1990-01-01",
        "country": null,
        "cellphone": "+27000000000",
        "last_login": "1700000000",
        "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5",
        "account_type": "Basic (Free)",
        "account_active": true,
        "account_verified": true,
        "address_line_1": "1 Example Street",
        "address_line_2": "",
        "address_postal_code": 2000,
        "address_state": "Gauteng",
        "address_country": "South Africa",
        "country_code": "+27",
        "profile_pic": null,
        "cellphone_verified": false,
        "time_offset": 7200,
        "time_limits": {
            "min_time": 1690000000,
            "max_time": 1700000000,
            "sensor_min_time": 1690000000,
            "sensor_max_time": 1700000000,
            "switch_min_time": null,
            "switch_max_time": null,
            "ws_min_time": null,
            "ws_max_time": null,
            "gps_min_time": null,
            "gps_max_time": null,
            "met_min_time": null,
            "met_max_time": null,
            "batmon_min_time": null,
            "batmon_max_time": null
        },
        "whatsapp_messages": 0,
        "sms_messages": 0,
        "api_calls": 1250
    }
}

Field description

Field name Description Type
user_id User id int
username Username (the email address used at sign up) str
email Email address str
firstname First name str
surname Last name str
gender Gender str
date_of_birth Date of birth str
country Country of birth str
cellphone Cellphone number str
last_login Last login time (epoch seconds, returned as a string) str
api_key Key stored on the user record at sign up (not the session api_key) str
account_type Basic (Free), Start-up, Growth, Premium or Enterprise str
account_active Whether the account is active bool
account_verified Whether the email address is verified bool
address_line_1 Address line 1 (empty string if not set) str
address_line_2 Address line 2 (empty string if not set) str
address_postal_code Postal code (empty string if not set) int
address_state State or province (empty string if not set) str
address_country Country str
country_code Dialling code used for the cellphone number, e.g. +27 str
profile_pic Profile picture str
cellphone_verified Whether the cellphone number is verified bool
time_offset Time offset in seconds (stored in minutes, see Update time offset) int
time_limits Earliest/latest history time overall and per device type, with time_offset applied. min_time is 0 and max_time is 2147483647 when there is no history json
whatsapp_messages Remaining WhatsApp message balance int
sms_messages Remaining SMS message balance int
api_calls Number of API calls made by the account int

Update profile

POST/update/profile

Used to update the caller's profile. Fields that are not sent keep their current value. A verified cellphone number cannot be changed.

Request

Auth: api_key · Content-type: application/json

Request body:

Fields can be sent as query parameters or a JSON body; query parameters win.

Field name Description Type
cellphone Cellphone number. Send the current number if it is not changing str
firstname [Optional] First name str
lastname [Optional] Last name str
gender [Optional] Gender str
date_of_birth [Optional] Date of birth str
address_line_1 [Optional] Address line 1 str
address_line_2 [Optional] Address line 2 str
address_postal_code [Optional] Postal code; must contain only digits str
address_state [Optional] State or province str
address_country [Optional] Country str
country_code [Optional] Dialling code, e.g. +27 str
profile_pic [Optional] Profile picture str

Request example:

https://spoilerinterface.com/interface/update/profile?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

{
    "firstname": "John",
    "lastname": "Doe",
    "cellphone": "+27000000000",
    "country_code": "+27",
    "address_postal_code": "2000"
}

Response

{
    "success": "Successfully updated user info"
}

Possible failed messages: Failed to update account. Cannot change a verified cellphone number., Invalid type: Postal code has to be a valid integer.

Update time offset

POST/update/profile/offset

Used to set the caller's time offset, which is applied to times returned by some endpoints.

Request

Auth: api_key · Content-type: application/json

Request body:

Send as query parameters or a JSON body; query parameters win.

Field name Description Type
time_offset Offset from UTC in minutes, e.g. 120 for UTC+2 int

Request example:

https://spoilerinterface.com/interface/update/profile/offset?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0&time_offset=120

Response

{
    "success": "Successfully updated user time offset"
}

A request without time_offset returns {"failed": "Missing field: time_offset"}.

Generate cellphone verification code

GET/cellphone/gen_verification_code

Used to generate a verification code for the account's cellphone number. After more than 3 requests you must wait 4 hours between requests; after 10 requests you must contact support.

Note: the server currently stores the code but the WhatsApp delivery call is disabled, so no message is sent.

Request

Auth: api_key

Request body:

None

Request example:

https://spoilerinterface.com/interface/cellphone/gen_verification_code?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Response

{
    "success": "A message has been sent with a verification code"
}

Already verified:

{
    "failed": "Your cellphone number has already been verified."
}

Too many requests (remaining_time_sec is an HH:MM:SS string):

{
    "failed": {
        "message": "You have exceeded the number of verification notification. Please wait 03:59:10 or contact Spoiler Support center.",
        "remaining_time_sec": "03:59:10"
    }
}

Verify cellphone

POST/cellphone/verification

Used to verify the account's cellphone number with the code from Generate cellphone verification code.

Request

Auth: api_key · Content-type: application/json

Request body:

Send as query parameters or a JSON body; query parameters win.

Field name Description Type
verification_code The verification code int

Request example:

https://spoilerinterface.com/interface/cellphone/verification?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0&verification_code=123456

Response

{
    "success": "Your cellphone number has been verified."
}

A missing code returns {"failed": "Missing field: verification_code"}; a wrong code returns a failed message starting with Failed to verify the code.

List sessions

GET/sessions

Used to list all login sessions of the caller's account.

Request

Auth: api_key

Request body:

None

Request example:

https://spoilerinterface.com/interface/sessions?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Response

{
    "success": [
        {
            "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
            "referrer": "https://spoilerinterface.com/board/login",
            "session_status": true,
            "session_error_log": null,
            "session_start_time": 1700007200,
            "session_end_time": null,
            "session_duration": null,
            "device_type": "",
            "session_location": "Country: South Africa, City: Johannesburg",
            "session_data": null,
            "session_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
            "session_ip_address": "203.0.113.10"
        }
    ]
}

Field description

Field name Description Type
user_agent Browser or client user agent str
referrer Referer header at login str
session_status Whether the session is active bool
session_error_log Error log, if any str
session_start_time Login time (epoch seconds) with the user's time offset applied int
session_end_time session_duration with the user's time offset applied int
session_duration Session duration int
device_type Device type str
session_location Location looked up from the IP address str
session_data Extra session data str
session_id Session id; this is the session's api_key str
session_ip_address Client IP address str

Log out a session

POST/sessions/logout

Used to end one of the caller's own sessions, e.g. a login on another browser.

Request

Auth: api_key · Content-type: application/json

Request body:

The request body is JSON.

Field name Description Type
session_id session_id from List sessions str

Request example:

https://spoilerinterface.com/interface/sessions/logout?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

{
    "session_id": "f0e1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a7f8e9"
}

Response

{
    "success": "Session logged out"
}

A session that does not exist or belongs to another user returns {"failed": "Session not found"}.

Stats

GET/stats

Used to get API usage and per-device data usage for the caller's account.

Request

Auth: api_key

Request body:

None

Request example:

https://spoilerinterface.com/interface/stats?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Response

{
    "success": {
        "user_id": 301659085216623,
        "total_user_api_calls": 1250,
        "total_data_usage_mb": 0.0,
        "most_active_device": {
            "device_type": "sensor",
            "device_id": 211674590684890,
            "device_name": "Door sensor",
            "data_usage_mb": 0.0,
            "last_seen": null,
            "history_records": 830
        },
        "least_active_device": {
            "device_type": "sensor",
            "device_id": 211674590684890,
            "device_name": "Door sensor",
            "data_usage_mb": 0.0,
            "last_seen": null,
            "history_records": 830
        },
        "device_stats": [
            {
                "device_type": "sensor",
                "device_id": 211674590684890,
                "device_name": "Door sensor",
                "data_usage_mb": 0.0,
                "last_seen": null,
                "history_records": 830
            }
        ]
    }
}

Field description

Field name Description Type
user_id User id int
total_user_api_calls Number of API calls made by the account int
total_data_usage_mb Sum of data_usage_mb over all devices. Device data usage is not tracked yet, so this is currently 0.0 float
most_active_device Device with the most history records (null if there are no devices) json
least_active_device Device with the fewest history records (null if there are no devices) json
device_stats All devices, sorted by history_records (descending) arr
device_type sensor, switch, batmon, met, ws, device or gps str
history_records Number of history rows for the device int
data_usage_mb Data usage for the device (currently always 0.0) float
last_seen Last seen time (currently always null) int