Account operations

This subsection covers various operations related to the management and maintenance of accounts.

It includes tasks such as blocking or unblocking accounts, changing the client plan associated with an account, retrieving detailed information about account subscriptions, and obtaining statistical data. It also includes other essential account management operations.

Client plan change on Forguard or Tags account

This endpoint allows service providers to switch the client plan to another one within Forguard or Tags account:

PUT /provider/accounts/{id}/client-plan

{id} - ID of account where the plan change will be applied.

The required fields for this request are the following:

  • tariff_plan_id: string - ID of the client plan you want to assign to the account. This ID can be obtained by using the GET /providers/client-plans endpoint.
  • app_id: string - ID of the application to which this tariff belongs.

Request example:

curl -X 'POST' \
'https://api.gps-trace.com/provides/accounts/111111/client-plan' \
-H 'accept: application/json' \
-H 'X-AccessToken: ' \
-H 'Content-Type: application/json' \
-d '{
"tariff_plan_id": "52ffXXXXXXXXXXXXdc89",
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea"
}'

200 Response:

{
"account_id": 111111,
"tariff_plan_id": "52ffXXXXXXXXXXXXdc89",
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea"
}

Block or unblock Forguard or Tags account

This endpoint is used to block/unblock Forguard or Tags account. When account is blocked, the client cannot access Forguard account. It's important to note that only activated accounts can be blocked.

PATCH /provider/accounts/{id}/set-blocked

{id} - account ID you want to block or unblock.

The mandatory field for this request:

  • blocked: boolean - Indicates the state of the blocked status. Set to true to block the account and false to unblock it.

Request example:

curl -X 'PATCH' \
'https://api.gps-trace.com/provider/accounts/11111/set-blocked' \
-H 'accept: application/json' \
-H 'X-AccessToken: ' \
-H 'Content-Type: application/json' \
-d '{
"blocked": true
}'

200 Response:

{
"id": 11111,
"pid": number,
"title": "string",
"description": "string",
"link_app": null,
"reg_apps": [
"b901da51-ce00-4af2-b978-8d0fca8ae1ea"
],
"created_at": number,
"updated_at": number,
"ack": number,
"subscriptions": {},
"service_apps": [],
"is_attached": false,
"attached_at": null,
"added_time": number,
"is_premium": false,
"type": 10,
"tariff_plans": {
"b901da51-ce00-4af2-b978-8d0fca8ae1ea": "string"
},
"blocked": true,
"client_payment_lifecycle": {}
}
  • id: unique identifier of the account.
  • pid: service provider account ID associated with the account.
  • title: name/title of the account
  • description: description or additional information about the account
  • link_app: application ID upon initial self-registration.
  • reg_apps: an array containing the IDs of the applications associated with the account. This indicates which applications the account has access to.
  • created_at: timestamp indicating the date and time when the account was created.
  • updated_at: timestamp indicating the date and time when the account was last updated.
  • ack: account activation date, represented as a timestamp.
  • subscriptions: object containing details about subscription associated with the account.
  • service_apps: array containing the applications associated with the account in which the service mode is enabled.
  • is_attached: boolean value indicating whether the account is linked by a service provider.
  • attached_at: if applicable, this field represents the date when the account was linked.
  • added_time: timestamp indicating the date and time when the account was added.
  • is_premium: boolean value indicating the active premium status subscription of the account.
  • type: type of the account:
    • 10 - managed by dealer account (Forguard, Tags)
    • 20 - dealer account
    • null - Ruhavik/Petovik account
  • tariff_plans: object containing details about the client plan of the account. ("app ID":"client plan ID")
  • blocked: boolean value indicating whether the account is currently blocked.
  • client_payment_lifecycle: Billing automation settings

Get account subscriptions

Retrieve information about the active subscription assigned to the account. Currently, premium subscriptions are applicable to accounts with access to Ruhavik. Therefore, when retrieving subscription information for accounts with access to other applications, the response will be empty.

GET /provider/accounts/{id}/subscriptions

{id} - The identifier of the account

200 Response example:

[
{
"account_id": 111111,
"app_id": "5a5ca87f-7cbe-4540-ab5d-77bf4bf69884",
"active": true,
"type": "td-stripe",
"subscription_id": "td-basic.yearly",
"expiry": number,
"purchase_data": {
"order_id": "string",
"auto_renew": boolean
},
"data": {}
}
]
  • app_id: ID of the application to which the subscription belongs
  • account_id: ID of the account
  • active: subscription status
  • type: type of subscription. Could be one of the following:
    • custom: this represents a custom subscription from GPS-Trace.
    • google: indicates a subscription purchased through Google Play.
    • ios-store: indicates a subscription purchased through the App Store.
    • paypal: represents a PayPal subscription purchased through the website.
    • td_paypal (telematic dealer paypal): this indicates a PayPal subscription purchased through the GPS-Trace Console by a dealer.
    • stripe: represents a Stripe subscription purchased through the website.
    • td_stripe (telematic dealer stripe): represents a Stripe subscription purchased through the GPS-Trace Console by a dealer.
    • space (promo subscription): indicates a Promo subscription from the GPS-Trace team, available when creating a Premium Ruhavik account through the GPS-Trace Console.
  • subscription_id: ID of the subscription
  • expiry: subscription expiration date
  • purchase_data: information about the purchase (order_id, auto_renew)

Set billing automation settings

This endpoint is used to set the billing automation settings for a Forguard account. It's important to note that only activated Forguard accounts can have their billing automation set.

PATCH /provider/accounts/{id}/set-payment-lifecycle

{id} - ID of the account (Forguard) you want to set the billing automation for.

Request example:

curl -X 'PATCH' \
'https://api.gps-trace.com/provider/accounts/11111/set-payment-lifecycle' \
-H 'accept: application/json' \
-H 'X-AccessToken: ' \
-H 'Content-Type: application/json' \

200 Response:

{
"id": 11111,
"pid": number,
"title": "string",
"description": "string",
"link_app": null,
"reg_apps": [
"b901da51-ce00-4af2-b978-8d0fca8ae1ea"
],
"created_at": number,
"updated_at": number,
"ack": number,
"subscriptions": {},
"service_apps": [],
"is_attached": false,
"attached_at": null,
"added_time": number,
"is_premium": false,
"type": 10,
"tariff_plans": {
"b901da51-ce00-4af2-b978-8d0fca8ae1ea": "string"
},
"blocked": false,
"client_payment_lifecycle": {
"payment_expected_at": 0,
"payment_notify_offset": 0,
"block_offset": 0,
"use_fleet_lifecycle": true
}
}
  • id: unique identifier of the account.
  • pid: service provider account ID associated with the account.
  • title: name/title of the account
  • description: description or additional information about the account
  • link_app: application ID upon initial self-registration.
  • reg_apps: an array containing the IDs of the applications associated with the account. This indicates which applications the account has access to.
  • created_at: timestamp indicating the date and time when the account was created.
  • updated_at: timestamp indicating the date and time when the account was last updated.
  • ack: account activation date, represented as a timestamp.
  • subscriptions: object containing details about subscription associated with the account.
  • service_apps: array containing the applications associated with the account in which the service mode is enabled.
  • is_attached: boolean value indicating whether the account is linked by a service provider.
  • attached_at: if applicable, this field represents the date when the account was linked.
  • added_time: timestamp indicating the date and time when the account was added.
  • is_premium: boolean value indicating the active premium status subscription of the account.
  • type: type of the account:
    • 10 - managed by dealer account (Forguard)
    • 20 - dealer account
    • null - Ruhavik account
  • tariff_plans: object containing details about the client plan of the account, specifically related to Forguard. ("app ID":"client plan ID")
  • blocked: boolean value indicating whether the account is currently blocked.
  • client_payment_lifecycle: Billing automation settings:
    • payment_expected_at - Date when the client payment is expected (payment deadline)
    • payment_notify_offset - Notification offset for client payment
    • block_offset - Offset for account blocking after payment due date
    • use_fleet_lifecycle - Use billing automation settings from account

Get accounts count

This method allows you to retrieve the count of accounts based on the filtering conditions specified in the request (e.g., all accounts, accounts with access to a specific application, activated or deactivated accounts, attached or unattached accounts)

GET /provider/accounts/count

Request body example:

curl -X 'GET' \
'https://api.gps-trace.com/provider/accounts/count?is_attached=true' \
-H 'accept: application/json' \
-H 'X-AccessToken: '

200 Response:

number

In the response, the number of accounts corresponding to your filter is included.

Get accounts limit

This endpoint retrieves the limits associated with a specific account.

GET /provider/accounts/{id}/limits

{id} - The identifier of the account

{app_id} - ID of the application (required)

Request example:

curl -X 'GET' \
'https://api.gps-trace.com/provider/accounts/111000/limits?app_id=5a5ca87f-7cbe-4540-ab5d-77bf4bf69884' \
-H 'accept: application/json' \
-H 'X-AccessToken: '

200 Response:

{
"account_id": number,
"unit": 10,
"geofence": 15,
"user": 1,
"triggers": 10,
"unit_extra_fields": null,
"unit_notify_settings": null
}
  • account_id: The identifier of the account.
  • unit: Maximum number of units user can create within this account
  • geofence: The maximum number of geofences allowed for this account.
  • user: The maximum number of users allowed for this account.
  • triggers: The maximum number of triggers allowed for this account.
  • unit_extra_fields: Additional fields.
  • unit_notify_settings: Account unit notify settings limit.