Overview

Customers form the core organizational units within each Service Organization (SO) in N-central. They represent your managed service clients and provide a structured way to:

Group and organize all devices belonging to a client
Apply consistent monitoring and management policies
Scale your MSP operations as you add new clients
Configure client-specific settings and features

Customers exist within the context of a Service Organization and can be further subdivided into Sites for more granular organization. This hierarchical structure enables efficient management of growing device networks and expanding client bases. This guide walks you through using the Customers API to automate and streamline your customer management operations. You'll learn how to:

Create a Customer
Retrieve Customer details
List all Customers
Manage Sites under a Customer
Handle Customer registration tokens

Creating a Customer

To add a new Customer to N-central, use the Create Customer endpoint within a Service Organization context.

Required Body Parameters

customerName: Name of the customer organization.
contactFirstName: First name of the primary contact.
contactLastName: Last name of the primary contact.

Optional Parameters

licenseType: Type of license (default: "Professional").
externalId: External identifier for integration.
contactEmail: Email address for notifications.
address: Physical location details.

Request Example

POST https://your-server/api/service-orgs/{soId}/customers
Authorization: Bearer <YOUR_TOKEN>
Content-Type: application/json

{
  "customerName": "TechCorp Industries",
  "contactFirstName": "Sarah",
  "contactLastName": "Johnson",
  "licenseType": "Professional",
  "contactEmail": "[email protected]",
  "street1": "456 Enterprise Ave",
  "city": "Chicago",
  "stateProv": "IL",
  "country": "US",
  "postalCode": "60601"
}

Response Example

Upon success, N-central returns a 201 status code with the created Customer's details.

{
  "data": {
    "customerId": 78901,
    "customerName": "TechCorp Industries",
    "orgUnitType": "CUSTOMER",
    "parentId": "12345",
    "contactFirstName": "Sarah",
    "contactLastName": "Johnson"
  }
}

Retrieving a Customer

Get detailed information about a specific Customer using their customerId.

Request Example

GET https://your-server/api/customers/{customerId}
Authorization: Bearer <YOUR_TOKEN>

Response Example

{
  "data": {
    "customerId": "78901",
    "customerName": "TechCorp Industries",
    "orgUnitType": "CUSTOMER",
    "parentId": "12345",
    "externalId": "TECH-001",
    "contactFirstName": "Sarah",
    "contactLastName": "Johnson",
    "contactEmail": "[email protected]",
    "licenseType": "Professional"
  }
}

Listing Customers

Retrieve all Customers across all Service Organizations with support for pagination.

Optional Query Parameters

pageSize: Items per page (default: 50).
pageNumber: Page to retrieve (starts at 1).
sortBy: Field to sort by.
sortOrder: Sort direction (ASC/DESC).

Request Example

GET https://your-server/api/customers?pageSize=20&pageNumber=1
Authorization: Bearer <YOUR_TOKEN>

Response Example

{
  "data": [
    {
      "customerId": "78901",
      "customerName": "TechCorp Industries",
      "orgUnitType": "CUSTOMER"
    },
    {
      "customerId": "78902",
      "customerName": "Global Systems Inc",
      "orgUnitType": "CUSTOMER"
    }
  ],
  "totalItems": 156,
  "pageNumber": 1,
  "pageSize": 20
}

Managing Sites Under a Customer

Listing Sites

Retrieve all sites associated with a specific Customer.

Request Example

GET https://your-server/api/customers/{customerId}/sites
Authorization: Bearer <YOUR_TOKEN>

Creating a Site

Add a new site under a Customer.

Request Example

POST https://your-server/api/customers/{customerId}/sites
Authorization: Bearer <YOUR_TOKEN>
Content-Type: application/json

{
  "siteName": "Downtown Office",
  "contactFirstName": "Michael",
  "contactLastName": "Brown",
  "licenseType": "Professional"
}

Customer Registration Tokens

Retrieve registration tokens for customer deployment.

Request Example

GET https://your-server/api/customers/{customerId}/registration-token
Authorization: Bearer <YOUR_TOKEN>

Response Example

{
  "data": {
    "registrationToken": "2f64ee5e-7c37-dce7-ffd2-d32912609623",
    "registrationTokenExpiryDate": "2024-05-01T23:59:00-04:00[America/New_York]"
  }
}

Error Handling

Common error responses include:

400 Bad Request: Invalid input or missing required fields.
401 Unauthorized: Authentication failure.
403 Forbidden: Insufficient permissions.
404 Not Found: Customer not found.
409 Conflict: Resource already exists.
429 Too Many Requests: Rate limit exceeded.

Error Response Format

{
  "status": 400,
  "message": "[ID=abcd] BAD REQUEST: Customer Create -- Name is required"
}