Add a new customer (for partners)

As a partner, the Surfsight API enables you to manage your devices smoothly by leveraging a hierarchical structure for each account. You can build your hierarchy for device management, including division of devices by organizations (parents) and by groups (children). As new end-users sign up with you for Surfsight services, we recommend that you first talk with them about possible ways to group and manage their devices based on these options. The structure they choose will most likely depend on the size and number of fleets they're managing, in addition to any other relevant organizational decisions.

Once you've mapped out vehicles and their devices to Surfsight organizations and groups, you can create those organizations and groups for the account - and add users and devices.

Prerequisite

These calls must be made by a user who is defined as a partner in the system and therefore, has credentials to access the Partner Portal. If you do not have these partner credentials, reach out to your technical account manager to receive the proper credentials.

The rest of this guide shows you how to use the Surfsight API to create a new customer in the system, following these steps:

  1. Authenticate yourself.
  2. Create organizations.
  3. Create groups.
  4. Add devices to your organizations.
  5. Add users to your organizations.
Note

For more information about the different API requests, take a look at our reference guide.

1. Authenticate yourself

Authenticate yourself before making any calls with the Surfsight API. For more details on authentication, see our authentication overview.

2. Create organizations

Create organizations with the POST /organizations request.

Copy
Copied
    curl --request POST https://api-prod.surfsight.net/v2/organizations
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '{

      "name": "Missouri fleet"
    }'
Note

The organizationID is returned in this call. Save this ID to use in other calls. You can also get the ID again from the GET /organizations request.

3. Create groups

Create groups with the POST /organizations/{orgId}/groups request.

Copy
Copied
    curl --request POST https://api-prod.surfsight.net/v2/organizations/{orgId}/groups
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '{

      "name": "St. Louis fleet"
    }'

4. Add devices

Add devices to your organizations:

  • for individual devices - with the POST /organizations/{orgId}/devices request

    curl --request POST https://api-prod.surfsight.net/v2/organizations/{orgId}/devices
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {token}'
--data-raw '{

    "imei": "357660101000198",
    "name": "Harry's car",
    "groupId": 32
}'

  • for multiple devices at once - with the POST /organizations/{orgId}/bulk-devices request

    Copy
    Copied
        curl --request POST https://api-prod.surfsight.net/v2/organizations/{orgId}/bulk-devices
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '[

      {
        "imei": "357660101000198",
        "name": "Harry's car",
        "groupId": 32
      },
      {
        "imei": "357660101000276",
        "name": "Ginny's car",
        "groupId": 26
      }
    ]'

    A list of accepted and rejected devices by IMEI number is returned.

5. Add users

Add users to your organizations with the POST /organizations/{orgId}/users request.

When creating a user, you also assign their role: restricted, user, administrator, or supervisor. For details about each role's credentials, see User types.

You can also assign the user to different groups.

Copy
Copied
    curl --request POST https://api-prod.surfsight.net/v2/organizations/{orgId}/users
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '{

      "email": "email@email.com",
      "password": "123Abcd!",
      "role": "user"
      "groupIds": [
                    32
                ]
    }'