ContactsLog inGet startedAsk Navixy AI

Activating a GPS device

In Navixy Repository API, GPS devices are referred to as inventory items and stored in user-created lists called inventories. Inventories are collections of devices used to organize and manage equipment more efficiently. They serve as logical groupings that help structure, track, and operate devices. A device cannot exist outside of inventory.

In this guide, you will learn how to add a device to an inventory and activate it. You can activate any device listed on the supported models page or a smartphone with the X-GPS Tracker app installed.

Types of GPS devices

Navixy Repository API supports two types of devices:

  • Devices capable of transmitting GPS data independently (referred to as masters).

  • Devices unable to contact GPS servers (referred to as slaves). They must be paired with master devices to transmit data to our servers; they cannot be activated independently. BT sensors are a common example of the second type.

How to activate a GPS device

Note that {BASE_URL} in sample requests is a placeholder for the URL you'll be using, which depends on your geographical location and the current version of the API. To learn the specific server URLs, see API environments.

Prerequisites

A GPS device ready for activation.

Step 1. Fetch device model specification

Navixy Repository API supports a wide variety of GPS devices, each with its own unique set of parameters for activation and communication. To work with any GPS device, you first need its specific parameters. You can view all specifications for all device models by making this request:

List master item models

get
/v0/inventory_item/master/model/list

Returns all master item models with their respective capabilities and specifications

Authorizations
OAuth2authorizationCodeRequired

OAuth 2.0 authentication for Europe. Use this for users based in Europe and adjacent regions.

Authorization URL: Token URL: Refresh URL:
Available scopes:
  • : OpenID Connect scope
  • : Basic user profile
  • : User e-mail address
Query parameters
qstringOptional

A search query string

limitinteger · int32 · max: 1000Optional

Maximum number of items to return (default: 100, max: 1000)

offsetinteger · int32Optional

The index of the first item to return (default: 0)

sortstringOptional

Sort expression. Supports one or more fields, optionally prefixed with - to indicate descending order. For example, vendor,-name

Responses
200

List of master item models

application/json
get
/v0/inventory_item/master/model/list
GET /repo/v0/inventory_item/master/model/list HTTP/1.1
Host: api.navixy.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": [],
  "has_more": true
}

Of course, you probably already know your model and want to fetch its specific parameters. That can be achieved by adding a query. For example, let's say your GPS device is Teltonika FM4200. Use this request:

curl -L \
  --request GET \
  --url "{BASE_URL}/inventory_item/master/model/list?q=Teltonika%20FM4200" \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

You'll get a response that looks like this:

{
    "data": [
        {
            "code": "telfm4200",
            "vendor": "Teltonika Telematics",
            "name": "Teltonika FM4200",
            "device_id_pattern": "[0-9]{15,16}",
            "communication": {
                "port": 47776,
                "protocols": {}
            },
            "base_activation_fields": [],
            "activation_methods": [
                {
                    "id": 28,
                    "title": "By tracker phone number",
                    "method_fields": [
                        {
                            "field": "apn_name",
                            "title": "APN",
                            "optional": true,
                            "pattern": "[-a-zA-Z0-9_.@ ]*"
                        },
                        {
                            "field": "apn_user",
                            "title": "Username",
                            "optional": true,
                            "pattern": "[-a-zA-Z0-9_.@ ]*"
                        },
                        {
                            "field": "apn_password",
                            "title": "Password",
                            "optional": true,
                            "pattern": "^[^\\p{Cntrl}\\uD800-\\uDFFF\\uE000-\\uF8FF]+$"
                        },
                        {
                            "field": "phone",
                            "title": "Phone number",
                            "optional": false,
                            "pattern": "^[0-9]{8,20}$"
                        }
                    ]
                },
                {
                    "id": 44,
                    "title": "By activation code and tracker phone number",
                    "method_fields": [
                        {
                            "field": "apn_name",
                            "title": "APN",
                            "optional": true,
                            "pattern": "[-a-zA-Z0-9_.@ ]*"
                        },
                        {
                            "field": "apn_user",
                            "title": "Username",
                            "optional": true,
                            "pattern": "[-a-zA-Z0-9_.@ ]*"
                        },
                        {
                            "field": "apn_password",
                            "title": "Password",
                            "optional": true,
                            "pattern": "^[^\\p{Cntrl}\\uD800-\\uDFFF\\uE000-\\uF8FF]+$"
                        },
                        {
                            "field": "phone",
                            "title": "Phone number",
                            "optional": false,
                            "pattern": "^[0-9]{8,20}$"
                        },
                        {
                            "field": "activation_code",
                            "title": "Activation code",
                            "optional": true,
                            "pattern": "[0-9]{3,20}"
                        }
                    ]
                }
            ]
        }
    ],
    "has_more": false
}

Remember the following parameters for the next steps:

  • code: The unique identifier for the model (e.g., telfm4200).

  • activation_methods: An array of supported activation methods. Note the id of the method you plan to use (e.g., 44).

  • method_fields: A list of field keys required for your chosen activation method (e.g., apn_name, phone).

Step 2. Create an inventory

Every inventory item requires an inventory. To create it, send the following request:

Create a new inventory

post
/v0/inventory/create

Adds a new inventory for the organization

Authorizations
OAuth2authorizationCodeRequired

OAuth 2.0 authentication for Europe. Use this for users based in Europe and adjacent regions.

Authorization URL: Token URL: Refresh URL:
Available scopes:
  • : OpenID Connect scope
  • : Basic user profile
  • : User e-mail address
Body
labelstringRequired

The inventory's label

Example: Dutch
descriptionstringRequired

The detailed inventory description

Example: Dutch branch office
Responses
200

Inventory created successfully

application/json
post
/v0/inventory/create
POST /repo/v0/inventory/create HTTP/1.1
Host: api.navixy.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "label": "Dutch",
  "description": "Dutch branch office"
}
{
  "id": 123
}

Use this request body:

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory/create' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "Paris Depot",
    "description": "Paris Vehicle Depot"
  }'

You will receive the ID of the created inventory:

{
  "id": 24
}

Step 3. Create a master inventory item

Create a new master item

post
/v0/inventory_item/master/create

Adds a master item for the organization

Authorizations
OAuth2authorizationCodeRequired

OAuth 2.0 authentication for Europe. Use this for users based in Europe and adjacent regions.

Authorization URL: Token URL: Refresh URL:
Available scopes:
  • : OpenID Connect scope
  • : Basic user profile
  • : User e-mail address
Body

Defines the request schema for /inventory_item/master/create

inventory_idinteger · int64Optional

Unique identifier for the inventory

Example: 12
modelstringOptional

A code of one of the supported models. See inventory_item/master/model/list

Example: telfmb125Pattern: [-a-z0-9_]{1,255}
device_idstringOptional

The server uses a unique identifier assigned to the device to authenticate and distinguish incoming data from different devices

Example: 123456789012345Pattern: ^[0-9a-zA-Z\-]{1,64}$
labelstringRequired

The inventory item label

Example: GPS tracker FMC130-001
asset_idinteger · int64Optional

Unique asset identifier for linking

Example: 21
Responses
200

Inventory item created successfully

application/json
post
/v0/inventory_item/master/create
POST /repo/v0/inventory_item/master/create HTTP/1.1
Host: api.navixy.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "inventory_id": 12,
  "model": "telfmb125",
  "device_id": "123456789012345",
  "label": "GPS tracker FMC130-001",
  "asset_id": 21
}
{
  "id": 123
}

Use this response body:

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory_item/master/create' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "inventory_id": 24,
    "model": "telfm4200",
    "device_id": "123456789012345",
    "label": "GPS tracker for Delivery Van 1"
  }'

Key parameters:

  • device_id: The unique identifier of the device, typically its IMEI.

  • model: Navixy's internal code of your device model that you learned in Step 1.

You will get the internal ID of the newly created item:

{
  "id": 34
}

Step 4. Activate the GPS device

To activate a device connected to a master-type inventory item, it must be preconfigured and exist in the organization's inventory. Upon activation, the device is assigned to the organization.

Send the following request:

Activate a master item

post
/v0/inventory_item/master/activate

Activates a created master device using a unique identifier. The device must be preconfigured and may exist either in the organization's inventory or in a dealer's inventory. Upon activation, the device is assigned to the organization

Authorizations
OAuth2authorizationCodeRequired

OAuth 2.0 authentication for Europe. Use this for users based in Europe and adjacent regions.

Authorization URL: Token URL: Refresh URL:
Available scopes:
  • : OpenID Connect scope
  • : Basic user profile
  • : User e-mail address
Body

Defines the request schema for /inventory_item/master/activate

idinteger · int64Required

Unique identifier for the master item

Example: 123
modelstringOptional

A code of one of the supported models. See inventory_item/master/model/list

Example: telfmb125Pattern: [-a-z0-9_]{1,255}
device_idstringOptional

The server uses a unique identifier assigned to the device to authenticate and distinguish incoming data from different devices

Example: 123456789012345Pattern: ^[0-9a-zA-Z\-]{1,64}$
activation_method_idinteger · int32Required

Unique identifier of one of the authentication methods supported by the model. See inventory_item/master/model/list

Responses
post
/v0/inventory_item/master/activate
POST /repo/v0/inventory_item/master/activate HTTP/1.1
Host: api.navixy.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 159

{
  "id": 123,
  "model": "telfmb125",
  "device_id": "123456789012345",
  "activation_method_id": 1,
  "fields": {
    "iridium_modem_imei": "123456789012345",
    "activation_code": "123"
  }
}
No content
curl -L \
  --request POST \
  --url '{BASE_URL}/inventory_item/master/activate' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 34,
    "device_id": "123456789012345",
    "model": "telfm4200",
    "activation_method_id": 44,
    "fields": {
      "phone": "15551234567",
      "activation_code": "54321"
    }
  }'

These are the key parameters you've learned in Step 1:

  • activation_method_id: A unique identifier of one of the authentication methods supported by the model.

  • fields : Combined set of field values needed for model activation, including:

    • Model-specific parameters

    • Activation method-specific parameters

You will receive an empty response body with the 204 No Content status.

Step 5. (Optional) Create and pair slave devices

A slave device doesn't transmit GPS data unless paired with a master device. Many slave devices are sensors connected via Bluetooth.

Create a new slave item

post
/v0/inventory_item/slave/create

Adds a slave item for the organization

Authorizations
OAuth2authorizationCodeRequired

OAuth 2.0 authentication for Europe. Use this for users based in Europe and adjacent regions.

Authorization URL: Token URL: Refresh URL:
Available scopes:
  • : OpenID Connect scope
  • : Basic user profile
  • : User e-mail address
Body

Defines the request schema for /inventory_item/slave/create

inventory_idinteger · int64Optional

Unique identifier for the inventory

Example: 12
labelstringRequired

The inventory item label

Example: Fuel sensor TD-150
asset_idinteger · int64Optional

Unique asset identifier for linking

Example: 21
master_idinteger · int64Optional

Unique identifier for the master item

Example: 123
Responses
200

Inventory item created successfully

application/json
post
/v0/inventory_item/slave/create
POST /repo/v0/inventory_item/slave/create HTTP/1.1
Host: api.navixy.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "inventory_id": 12,
  "label": "Fuel sensor TD-150",
  "asset_id": 21,
  "master_id": 123
}
{
  "id": 123
}

To create a slave inventory item, use this request body:

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory_item/slave/create' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "inventory_id": 24,
    "label": "BT sensor 1"
  }'

Just like with the master, the response will contain the ID of the created item.

{
  "id": 556
}

Now that you've created a slave device, you need to pair it with a master device. To do this, send the following request:

Pair a slave with a master item

post
/v0/inventory_item/slave/pair

Pairs a slave device with a master device within the organization's inventory system. Used to establish logical associations between devices (e.g., sensors with trackers). Both devices belong to the same organization but may be located in different inventories.

Authorizations
OAuth2authorizationCodeRequired

OAuth 2.0 authentication for Europe. Use this for users based in Europe and adjacent regions.

Authorization URL: Token URL: Refresh URL:
Available scopes:
  • : OpenID Connect scope
  • : Basic user profile
  • : User e-mail address
Body

Defines the request schema for /inventory_item/slave/pair

idinteger · int64Required

Unique identifier for the slave item

Example: 321
master_idinteger · int64Required

Unique identifier for the master item

Example: 123
Responses
post
/v0/inventory_item/slave/pair
POST /repo/v0/inventory_item/slave/pair HTTP/1.1
Host: api.navixy.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "id": 321,
  "master_id": 123
}
No content

Use this request body:

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory_item/slave/pair' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 556,
    "master_id": 34
  }'

You will receive an empty response body and a 204 No Content status.

Alternatively, you can create and pair the slave device with a single request:

curl -L \
  --request POST \
  --url '{BASE_URL}/inventory_item/slave/create' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "inventory_id": 24,
    "label": "BT sensor 1",
    "master_id": 34
  }'

The response will be the same as with an ordinary creation request (the id of the created item).

Congratulations! You've successfully activated your device. Next, you can assign it to an asset.

PreviousGuidesNextCreating a custom asset

Last updated

Was this helpful?