Import target users from Excel for a customer

As a Reseller you can bulk-import target users for a customer by uploading an Excel or CSV file through the API. The flow mirrors the platform UI: upload the file, map columns to user fields, preview the parsed rows, then confirm the import. Use a credential with Client Role = Reseller. Send X-KEEPNET-Company-Id with every request so the users are created under the correct customer.

POST /api/companies/search

Get the customer's Company ID first. Use the resourceId from the response as X-KEEPNET-Company-Id in all subsequent 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

OAuth2clientCredentialsRequired

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

Token URL:

Body

pageNumberintegerRequiredExample: 1

pageSizeintegerRequiredExample: 10

orderBystringRequiredExample: CreateTime

ascendingbooleanRequiredExample: false

isTargetUserCountExceededLimitbooleanOptional

If true, only companies exceeding license limit are returned

Example: false

Responses

200

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/companies/search

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": ""
  }
}

200

{
  "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:25.297Z",
        "createTime": "2026-03-09T17:38:25.297Z",
        "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:25.297Z",
            "createTime": "2026-03-09T17:38:25.297Z",
            "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"
  ]
}

POST /api/target-users/example-file

Downloads an example Excel template with the expected column headers. Use this as a reference when preparing your file. Send X-KEEPNET-Company-Id. Body: exportType ("Csv" or "Excel").

Get example user list file

post

Required scopes

This endpoint requires the following scopes:

: API

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Body

exportTypestringRequired

Excel or Csv

Example: Excel

Responses

200

No content

post

/api/target-users/example-file

POST /api/target-users/example-file HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 22

{
  "exportType": "Excel"
}

200

No content

Example body:

{
  "exportType": "Excel"
}

POST /api/target-users/upload

Uploads the Excel/CSV file containing target users. Send the file as multipart/form-data with the field name File. Send X-KEEPNET-Company-Id. The response returns a transactionId — use it in all subsequent steps.

Upload target user list file

post

Required scopes

This endpoint requires the following scopes:

: API

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Body

Filestring · binaryOptional

Responses

200

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/target-users/upload

POST /api/target-users/upload HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "File": "binary"
}

200

{
  "data": {
    "transactionId": "text",
    "rowCount": 1,
    "columnCount": 1,
    "duplicateCount": 1
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

Example request headers:

Authorization: Bearer <your_access_token>
Content-Type: multipart/form-data
X-KEEPNET-Company-Id: xC5kfGz7w2Nz

GET /api/target-users/upload/{transactionId}

Returns the upload summary: detected column headers, sheet names, and row count. Use the column names from this response to build the field mappings in the next step. Send X-KEEPNET-Company-Id.

Get uploaded target user list file summary

get

Required scopes

This endpoint requires the following scopes:

: API

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Path parameters

transactionIdstringRequired

Responses

200

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

get

/api/target-users/upload/{transactionId}

GET /api/target-users/upload/{transactionId} HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

{
  "data": {
    "fileType": "text",
    "sheetNames": [
      "text"
    ],
    "data": null,
    "fileFieldNames": [
      "text"
    ]
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

POST /api/target-users/create-mapping

Maps Excel column headers to Keepnet target user fields and starts the mapping job. Send X-KEEPNET-Company-Id. Body: transactionId, fieldMappings (array of column-to-field pairs), and optionally targetGroupResourceIds to assign imported users to existing groups.

Creates a mapping job for transaction id

post

Required scopes

This endpoint requires the following scopes:

: API

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Body

transactionIdstringRequiredExample: <transactionId-from-upload>

targetGroupResourceIdsstring[]Optional

Optional: assign users to groups

Responses

200

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/target-users/create-mapping

POST /api/target-users/create-mapping HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 311

{
  "transactionId": "<transactionId-from-upload>",
  "targetGroupResourceIds": [],
  "fieldMappings": [
    {
      "excelColumnName": "Email",
      "fieldName": "email"
    },
    {
      "excelColumnName": "First Name",
      "fieldName": "firstName"
    },
    {
      "excelColumnName": "Last Name",
      "fieldName": "lastName"
    },
    {
      "excelColumnName": "Department",
      "fieldName": "department"
    }
  ]
}

200

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

Example body:

{
  "transactionId": "abc123-def456",
  "targetGroupResourceIds": [],
  "fieldMappings": [
    { "excelColumnName": "Email", "fieldName": "email" },
    { "excelColumnName": "First Name", "fieldName": "firstName" },
    { "excelColumnName": "Last Name", "fieldName": "lastName" },
    { "excelColumnName": "Department", "fieldName": "department" }
  ]
}

The response returns a resourceId for the mapping job — use it to poll the job status.

GET /api/target-users/mapping-job/{resourceId}

Polls the mapping job status. The job parses Excel rows and validates them against the field mappings. Send X-KEEPNET-Company-Id. Poll until the job status indicates completion, then proceed to preview or import.

Gets the status of the mapping job

get

Required scopes

This endpoint requires the following scopes:

: API

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Path parameters

resourceIdstringRequired

Responses

200

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

get

/api/target-users/mapping-job/{resourceId}

GET /api/target-users/mapping-job/{resourceId} HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

POST /api/target-users/{transactionId}/search

Preview the parsed target users before importing. Returns a paginated list of temporary user records parsed from the uploaded file. Send X-KEEPNET-Company-Id. Use this to verify the data looks correct before confirming the import.

Returns a list of tmp target users to be imported

post

Required scopes

This endpoint requires the following scopes:

: API

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Path parameters

transactionIdstringRequired

Body

pageNumberintegerRequiredExample: 1

pageSizeintegerRequiredExample: 20

orderBystringOptionalExample: Email

ascendingbooleanOptionalExample: true

Responses

200

application/json

statusstringOptional

messagestring · nullableOptional

newUserCountinteger · int32Optional

existingUserCountinteger · int32Optional

invalidUserCountinteger · int32Optional

post

/api/target-users/{transactionId}/search

POST /api/target-users/{transactionId}/search HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 140

{
  "pageNumber": 1,
  "pageSize": 20,
  "orderBy": "Email",
  "ascending": true,
  "filter": {
    "condition": "and",
    "searchInputTextValue": null,
    "filterGroups": []
  }
}

200

{
  "status": "text",
  "message": "text",
  "items": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalNumberOfPages": 1,
    "totalNumberOfRecords": 1,
    "results": [
      {
        "resourceId": "text",
        "email": "text",
        "firstName": "text",
        "lastName": "text",
        "department": "text",
        "priority": "text",
        "transactionId": "text",
        "validationDetail": [
          {
            "fieldName": "text",
            "message": "text"
          }
        ],
        "customFields": [
          {
            "resourceId": "text",
            "name": "text",
            "dataType": "text",
            "value": "text"
          }
        ],
        "createTime": "2026-03-09T17:38:25.297Z",
        "updateTime": "2026-03-09T17:38:25.297Z",
        "status": "text",
        "phoneNumber": "text",
        "timeZone": "text",
        "preferredLanguage": "text"
      }
    ]
  },
  "newUserCount": 1,
  "existingUserCount": 1,
  "invalidUserCount": 1
}

POST /api/target-users/{transactionId}/import

Confirms and imports the parsed users into the customer's target user list. Send X-KEEPNET-Company-Id. Body: importType (e.g. "All" to import all rows, or "Selected" with selectedResourceIds to import specific users).

Imports a list of tmp target users

post

Required scopes

This endpoint requires the following scopes:

: API

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Path parameters

transactionIdstringRequired

Body

importTypestringRequired

All or Selected

Example: All

selectedResourceIdsstring[]Optional

Required when importType is Selected

Responses

200

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/target-users/{transactionId}/import

POST /api/target-users/{transactionId}/import HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 45

{
  "importType": "All",
  "selectedResourceIds": []
}

200

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

Example body (import all):

{
  "importType": "All",
  "selectedResourceIds": []
}

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.
400 Bad Request — File format not supported, or field mappings do not match the uploaded file's columns. Verify column names from GET /api/target-users/upload/{transactionId}.
404 Not Found — Invalid transactionId or resourceId. The transaction may have expired — re-upload the file.

Platform UI: Import target users under Company → Target Users → Import. Target Users →

Related: Add target users for a customer → for adding users one by one via API. Scope API requests to a customer → for how Company ID is used across endpoints.

PreviousAdd target users for a customer NextList or export target users for a customer

Last updated 4 hours ago

hashtagPOST /api/companies/search

hashtagRetrieves a list of all companies

hashtagPOST /api/target-users/example-file

hashtagGet example user list file

hashtagPOST /api/target-users/upload

hashtagUpload target user list file

hashtagGET /api/target-users/upload/{transactionId}

hashtagGet uploaded target user list file summary

hashtagPOST /api/target-users/create-mapping

hashtagCreates a mapping job for transaction id

hashtagGET /api/target-users/mapping-job/{resourceId}

hashtagGets the status of the mapping job

hashtagPOST /api/target-users/{transactionId}/search

hashtagReturns a list of tmp target users to be imported

hashtagPOST /api/target-users/{transactionId}/import

hashtagImports a list of tmp target users

hashtagCommon errors

POST /api/companies/search

Retrieves a list of all companies

POST /api/target-users/example-file

Get example user list file

POST /api/target-users/upload

Upload target user list file

GET /api/target-users/upload/{transactionId}

Get uploaded target user list file summary

POST /api/target-users/create-mapping

Creates a mapping job for transaction id

GET /api/target-users/mapping-job/{resourceId}

Gets the status of the mapping job

POST /api/target-users/{transactionId}/search

Returns a list of tmp target users to be imported

POST /api/target-users/{transactionId}/import

Imports a list of tmp target users

Common errors