User

Properties of a user.

Name	Type	Description
username	string	Unique mail address of the user
password	string	Password of the user
language	string	Default language to use in emails or when the client doesn't provide an explicit language via the header Language or Accept-Language. This should be in the ISO 639-1 (two letter) format. Supported languages are: en, de
timezone	string	Default timezone of the clients to use for API requests that did not set a Client-Date header. For requests with an API-Key this is only used when the time_offset expired or was not set previously. The string is expected as an TZ identifier like Europe/Berlin
timezone_transition	bool	Autoamtically adjust the times of entries when a time transition (e.g. from winter to summer) was performed. The time before and after the transition will be the same for the client
current_ressources	UserRessources	How many ressources the user already utilized from his subscription
subscriptions	UserRessources[]	All valid subscriptions
subscription_errors	SubscriptionState[]	Errors that occured during checking the license like no license, API request limit or entries reached
subscription_warnings	SubscriptionState[]	Warnings that occured during checking the license. A warning is in general generated when about 90 % of a ressource are already utilized
mail_subscriptionExpires	bool	Send a reminder mail before the subscription expires
mail_ressourceUsed	bool	Send a notification mail if more than 90 % of the allocated resources in the users subscription plan have been used (only for selected properties)

Warning

This page does not contain all user endpoints. For example, the endpoints for purchasing or upgrading a license have been omitted, as these are not intended to be used by external tools.

UserRessources

This object contains either the currently utilized ressources by the user, or all subscriptions the user booked with the available ressources.

Properties

Name	Type	Description
entries	int	Number of entries in the future
attributes	int	Number of attributes
tokens	int	Number of tokens that are valid and do have a validation time > 10 hours
socket_connections	int	Number of currently connected clients to the web socket
api_calls	int	Number of API calls

When this ressource is used within the subscriptions field in the user object, the following subscription details are also available.

Name	Type	Description
valid_from	Date	Begin of the subscription
valid_to	Date	End of the subscription
plan_id	int	Internal number of the subscription plan
plan_description	string	Short description String of the subscription plan
parameter_length	int	Maximum allowed character sum lenght of all parameters for one entry

SubscriptionState

Contains either a warning or error message about the current subscription state.

Name	Type	Description
id	string	Unique ID of the subscription error / warning
message	string	Description of the problem
current	int	Contains for some problems the currently used ressources
limit	int	Contains for some problems the limit of ressource for the subscription profile

Create user (POST /user)

Details

Creates a user. To use your account afterwards, you have to validate your email address with the endpoint Validate email address of user and the token we send you to your mail address.

Request body

See properties for values, example:

{
    "username": "myuser@mail.de",
    "password": "mySecretPassword",
    "language": "de"
}

Response codes

• 201 User created
• 400 Invalid values for fields supplied

Validate email address of user (POST /user/mail/verify)

Details

Endpoint to validate the email address for a user after an account creation or when the user changed its mail address.

Request body

Name	Type	Description
token	string	Secret token that was sent by mail to the users email address

Response codes

• 200 Email address validated
• 403 Token is not valid or expired

Delete user (DELETE /user)

Details

Deletes your user account.

Response codes

• 200 User deleted
• 400 Invalid username supplied
• 401 Authentication failed
• 404 The username was not found

Patch user (PATCH /user/{username})

Details

Updates at least one property of the user.

Request parameters

Name	Type	Description
{username}	string	The unique name of the user

Request body

See User properties for available options. When you want to update the email or password, you have to be authenticated by username and password. The change of the email requires an additional post to the endpoint POST /user/mail/verify-update with the token we send you in the request body.

Response codes

• 200 User updated
• 201 User was not updated because nothing was changed
• 400 Invalid username supplied
• 401 Authentication failed
• 404 The user was not found

Reset password (request) (POST /user/password-reset/request)

Details

Requests a password reset for a user without knowing the old password of the user. You have to call the endpoint Reset password (execute) to complete the password reset.

Request body

Name	Type	Description
username	string	E-Mail of the user to send the password reset request
os_desc	string	Operating System and user agent of the browser / client which requested the password reset. This will be displayed in the E-Mails content

Response body

OK

Response codes

• 200 E-Mail with the reset token was successfully sent, or the user does not exist
• 400 Invalid username supplied

Reset password (execute) (POST /user/password-reset/execute)

Details

Executes a request to reset the password for a user without knowing the old password of the user.

Request body

Name	Type	Description
token	string	Secret token obtained by mail. The token was sent after calling the endpoint Reset password (request)
password	string	New password to set for the user

Response codes

• 200 Password was set successfull
• 403 Secret token is not valid / cannot be used

Get user (GET /user[/lastChange])

Details

Fetches the details for the currently authorized user.

Response body

{
    "username": "username@rpjosh.de",
    "last_change": "2023-09-02T13:12:09",
    "language": "en",
    "timezone": "UTC",
    "mail_subscriptionExpires": 1,
    "mail_ressourceUsed": 1,
    "subscriptions": [
        {
            "entries": 200,
            "attributes": 30,
            "api_calls": 20000,
            "tokens": 50,
            "valid_to": "2023-10-10",
            "valid_from": "2023-10-07",
            "plan_id": 10,
            "plan_description": "Standard"
        }
    ],
    "current_ressources": {
        "entries": 0,
        "attributes": 9,
        "api_calls": 379,
        "tokens": 25
    }
}

Response codes

• 200 Fields returned
• 401 Authentication failed

Get countries (GET /country)

Details

Returns a list of countries that can be used for the application.

A country has the following properties.

Name	Type	Description
id	int	Unique ID of the country
name	string	Name of the country
iso	string	ISO country code as defined by ISO 3166 (alphpa-2)
ip_match	boolean	If your client IP matches the country

Response body

[
  {
    "id": 1,
    "name": "Afghanistan",
    "iso": "AF",
    "ip_match": false
  },
  {
    "id": 2,
    "name": "Albania",
    "iso": "AL",
    "ip_match": true
  },
  {
    "id": 3,
    "name": "Algeria",
    "iso": "DZ",
    "ip_match": false
  }
]

Response codes

• 200 Fields returned