Overview

Service Organizations (SOs) represent the foundational level of your organizational structure. Each SO operates as an independent MSP organization within your N-central instance, maintaining its own unique ecosystem of:

Customer hierarchies
User and technician accounts
Monitoring rules and notifications
Feature sets and configurations

N-central administrators can manage multiple Service Organizations, each serving different MSP businesses or divisions. This API guide walks you through programmatically managing these Service Organizations, enabling you to automate and streamline your organizational structure. You'll learn how to:

Create a Service Organization
Retrieve Service Organization details
List all Service Organizations
Manage customers under a Service Organization

Creating a Service Organization

To add a new Service Organization, use the Create Service Organization endpoint and provide the organization's essential details.

Required Body Parameters

soName: Name of the service organization.
contactFirstName: First name of the primary contact.
contactLastName: Last name of the primary contact.

Optional Parameters

externalId: External identifier for integration purposes.
contactEmail: Email address for the organization.
phone: Contact phone number.
address: Physical address details (e.g., street1, street2, city).

Request Example

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

{
  "soName": "Acme IT Services",
  "contactFirstName": "John",
  "contactLastName": "Smith",
  "contactEmail": "[email protected]",
  "phone": "555-0123",
  "street1": "123 Tech Lane",
  "city": "Springfield",
  "stateProv": "IL",
  "country": "US",
  "postalCode": "62701"
}

Response Example

Upon success, N-central returns a 201 status code along with the details of the created Service Organization, including the soId, which you'll need for future requests.

{
  "data": {
    "soId": 12345,
    "soName": "Acme IT Services",
    "orgUnitType": "SO",
    "contactFirstName": "John",
    "contactLastName": "Smith",
    "contactEmail": "[email protected]"
  }
}

Retrieving a Service Organization

To get details about a specific Service Organization, use the Get Service Organization endpoint with the soId.

Request Example

GET https://your-server/api/service-orgs/{soId}
Authorization: Bearer <YOUR_TOKEN>

Response Example

{
  "data": {
    "soId": "12345",
    "soName": "Acme IT Services",
    "orgUnitType": "SO",
    "parentId": "1",
    "externalId": "ACME-001",
    "contactFirstName": "John",
    "contactLastName": "Smith",
    "contactEmail": "[email protected]",
    "phone": "555-0123"
  }
}

Listing Service Organizations

To retrieve all Service Organizations, use the List Service Organizations endpoint. This endpoint supports pagination for handling large datasets efficiently.

Optional Query Parameters

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

Request Example

GET https://your-server/api/service-orgs?pageSize=10&pageNumber=1
Authorization: Bearer <YOUR_TOKEN>

Response Example

{
  "data": [
    {
      "soId": "12345",
      "soName": "Acme IT Services",
      "orgUnitType": "SO"
    },
    {
      "soId": "12346",
      "soName": "TechCorp Solutions",
      "orgUnitType": "SO"
    }
  ],
  "totalItems": 45,
  "pageNumber": 1,
  "pageSize": 10
}

Managing Customers Under a Service Organization

Listing Customers

Retrieve all customers associated with a specific Service Organization.

Request Example

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

Creating a Customer

Add a new customer under a Service Organization.

Request Example

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

{
  "customerName": "Client Corp",
  "contactFirstName": "Jane",
  "contactLastName": "Doe",
  "licenseType": "Professional"
}

Error Handling

Here are common error responses you might encounter:

400 Bad Request: Invalid input format or missing required fields.
401 Unauthorized: Invalid or expired token.
403 Forbidden: Insufficient permissions.
404 Not Found: Service Organization not found.
429 Too Many Requests: Rate limit exceeded.

Error Response Format

{
  "status": 400,
  "message": "[ID=abcd] BAD REQUEST: SO Create -- Service Organization name is required"
}