User profile¶
Get profile¶
/user/profileUsed 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 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¶
/update/profileUsed 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¶
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¶
/update/profile/offsetUsed 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¶
A request without time_offset returns {"failed": "Missing field: time_offset"}.
Generate cellphone verification code¶
/cellphone/gen_verification_codeUsed 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¶
Already 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¶
/cellphone/verificationUsed 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¶
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¶
/sessionsUsed 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¶
/sessions/logoutUsed 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
Response¶
A session that does not exist or belongs to another user returns {"failed": "Session not found"}.
Stats¶
/statsUsed 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 |