Guide

Onboard a customer

Create a customer organization, invite its Owner, choose its plan and give it devices, all from your own systems.

Each of your customers is an organization under yours, with its own users, devices and webhook endpoints. Its users sign in to a portal that shows your branding, not HoundSat's. Onboarding one takes four requests; you need an Owner or Admin token of your reseller organization.

1. Create the customer

Create an organization with its name. It is created under your organization, as a customer.

Request

curl -X POST https://api.houndsat.com/api/json/organizations \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data": {"type": "organization", "attributes": {"name": "Northwind Freight"}}}'

Response201 Created

{
  "data": {
    "type": "organization",
    "id": "c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14",
    "attributes": {
      "name": "Northwind Freight",
      "level": "customer",
      "parent_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "status": "active",
      "default_plan_id": null,
      "users_count": 0,
      …
    }
  }
}

Keep its id: the next steps use it.

2. Invite its Owner

An organization's first user must be its Owner. Invite them with the customer's id as organization_id. They get an email, with your branding, inviting them to set a password. The link is valid for 7 days.

Request

curl -X POST https://api.houndsat.com/api/json/users \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "user",
      "attributes": {
        "email": "[email protected]",
        "name": "Dana Okafor",
        "role": "owner",
        "organization_id": "c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14"
      }
    }
  }'

If the email bounces or the link expires, resend the invite; if the address was wrong, delete the user (allowed until they accept) and invite the right one. The Owner can then invite their own Admins and Staff.

3. Set its plan

The customer's devices are billed on its default plan, one of your retail plans. Find the plan's id, then set it:

Your active retail plans

curl -g "https://api.houndsat.com/api/json/plans?filter[kind]=retail&filter[status]=active" \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"

Set the default plan

curl -X PATCH https://api.houndsat.com/api/json/organizations/c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14/default_plan \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "organization",
      "id": "c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14",
      "attributes": {"plan_id": "9b2e4f61-7c3a-4d05-a8e9-3f1c6b0d5a72"}
    }
  }'

A device can override it with a plan of its own (Set a device's plan). Devices without any plan aren't billed, so set one before the month ends.

4. Give it devices

Move SIMs from your inventory to the customer, up to 500 per request. You can also import new SIMs straight into the customer with customer_id; see Manage devices.

Request

curl -X POST https://api.houndsat.com/api/json/devices/bulk/reassign \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "customer_id": "c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14",
      "ids": ["5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8", "0b6d4e2a-1c9f-4a3b-8e5d-7f2c0a9b6d13"]
    }
  }'

5. Hand over to its developers

To receive their devices' messages on their own servers, the customer's Owner or an Admin adds a webhook endpoint, from their portal or with the API. Point their developers to Receiving webhooks: it covers the request they'll receive, how to verify its signature and how retries work.

Later: suspend, rename, remove

Suspending a customer stops its users from signing in and its devices from being activated or assigned. Suspending, deactivating and unassigning its devices still work, so you can wind a fleet down. Reactivate with "status": "active".

Suspend a customer

curl -X PATCH https://api.houndsat.com/api/json/organizations/c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14/status \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "organization",
      "id": "c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14",
      "attributes": {"status": "suspended"}
    }
  }'

Rename it with Rename an organization. A customer organization can only be deleted by its own Owner.