Scope API requests to a customer

As a Reseller you manage multiple customer companies. Most list/report endpoints return data for all companies you manage. To get or change data for one specific customer, send that customer’s Company ID in the request. This page explains how Reseller scope works and where to pass Company ID.

---

POST /api/companies/search

Get the customer's Company ID. Use the resourceId of the desired company as X-KEEPNET-Company-Id in scoped requests.

Retrieves a paginated list of all companies you manage with license details. Each item includes resourceId — use it as the Company ID for scoped requests. Test it: Authorize with Client ID/Secret, then Send — request body is pre-filled.

Retrieves a list of all companies

post

Required scopes

This endpoint requires the following scopes:

• : API

Authorizations

oauth2bearerAuth

OAuth2clientCredentialsRequired

Client ID and Client Secret from Company → Company Settings → REST API. Enter credentials to auto-fetch token.

Token URL:

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

pageNumberintegerRequiredExample: 1

pageSizeintegerRequiredExample: 10

orderBystringRequiredExample: CreateTime

ascendingbooleanRequiredExample: false

isTargetUserCountExceededLimitbooleanOptional

If true, only companies exceeding license limit are returned

Example: false

Responses

200

OK

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/companies/search

HTTPcURLJavaScriptPython

POST /api/companies/search HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 126

{
  "pageNumber": 1,
  "pageSize": 10,
  "orderBy": "CreateTime",
  "ascending": false,
  "filter": {
    "Condition": "AND",
    "SearchInputTextValue": ""
  }
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

OK

{
  "data": {
    "limitExceededCompanyCount": 1,
    "pageNumber": 1,
    "pageSize": 1,
    "totalNumberOfPages": 1,
    "totalNumberOfRecords": 1,
    "results": [
      {
        "companyName": "text",
        "companyResourceId": "text",
        "resellerName": "text",
        "industryName": "text",
        "industryResourceId": "text",
        "licenseTypeName": "text",
        "licenseTypeResourceId": "text",
        "isNumberOfUsersLimited": true,
        "numberOfUsers": "text",
        "privacyDurationId": 1,
        "licenceExpired": true,
        "licenseEndDate": "2026-03-09T17:38:24.076Z",
        "createTime": "2026-03-09T17:38:24.076Z",
        "targetUserCount": 1,
        "children": [
          {
            "companyName": "text",
            "companyResourceId": "text",
            "resellerName": "text",
            "industryName": "text",
            "industryResourceId": "text",
            "licenseTypeName": "text",
            "licenseTypeResourceId": "text",
            "isNumberOfUsersLimited": true,
            "numberOfUsers": "text",
            "privacyDurationId": 1,
            "licenceExpired": true,
            "licenseEndDate": "2026-03-09T17:38:24.076Z",
            "createTime": "2026-03-09T17:38:24.076Z",
            "targetUserCount": 1,
            "children": "[Circular Reference]",
            "tags": [
              "text"
            ],
            "deletedTargetUserCount": 1,
            "inactiveTargetUserCount": 1,
            "monthlyActiveUserCount": 1
          }
        ],
        "tags": [
          "text"
        ],
        "deletedTargetUserCount": 1,
        "inactiveTargetUserCount": 1,
        "monthlyActiveUserCount": 1
      }
    ]
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

From the response, pick the company and note its resourceId. Use that value as X-KEEPNET-Company-Id or companyId in the endpoints listed under "Where to use Company ID" below.

---

How Reseller scope works

• Without Company ID: Endpoints such as POST /api/companies/search and GET /api/companies/my return data for every company you (the Reseller) manage.

• With Company ID: To limit results or actions to a single customer (e.g. training report, phishing campaigns, target users), send the customer’s Company ID so the API scopes the response or operation to that company.

---

How to send Company ID

Use one of these:

• Header (recommended): X-KEEPNET-Company-Id: <companyResourceId>

• Query: ?companyId=<companyResourceId>

• Path: Some endpoints use {companyId} or {resourceId} in the path (e.g. GET /api/companies/{resourceId}).

Obtain customer Company IDs from List companies with license details → (POST /api/companies/search). The response includes resourceId per company — use that as X-KEEPNET-Company-Id or companyId. Use dummy/placeholder IDs in examples (H8d).

---

Where to use Company ID

• Reports: Training, phishing, gamification, executive summaries, audit logs — pass Company ID to get that customer’s data. View customer's enrollment list and report →, View customer's enrollment sending, certificates, and notifications →, View customer's campaign list and report →, Pull executive report data for a customer →. Endpoint details: see Endpoints in the API Reference sidebar (TrainingReport, PhishingCampaign, ExecutiveReport, etc.).

• Company & Users: Add target users, target groups, enroll users in training, manage system users, set up SCIM — use Company ID to scope the operation to one customer. Add target users for a customer →, List or export target users for a customer →, List and create target groups for a customer →, Set up SCIM for a customer →, Add system user for a customer →. To create a new company (onboard): Create a company →. To get, update, or delete a company: Get a company →, Update a company →, Delete a company →.

• Phishing simulation: List scenarios and create/start campaigns for a customer. List phishing scenarios for a customer →, Create and start phishing campaign for a customer →.

Quickstart: Company ID usage is summarized in the Quickstart → under “Reseller: scope by Company ID”.

---

Common errors

• 403 Forbidden — Credential is not Reseller, or the Company ID is not one you manage. Set Client Role = Reseller. Roles and permissions →

• 401 Unauthorized — Missing or invalid token. Request a new token via POST /connect/token.

• 404 Not Found — Invalid or unknown Company ID. Verify from POST /api/companies/search.