Ctrlk
Log inGet startedAsk Navixy AI
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Employee import

Create many employees at once from a spreadsheet, through a background import process.

Employee import creates many employees at once from a spreadsheet, rather than one call per person.

Convert the spreadsheet first with data/spreadsheet/parse, which stores it as a tab-separated file and returns its name. Pass that name to employee/import/start as filename, follow the process with read or list, and collect the rows that failed validation with download_failed.

API actions

API base path: /employee/import.

Operations that list no errors of their own return only the general error codes.

Create the TSV file first with /data/spreadsheet/parse, which returns its name as file_id. Pass that name to start as filename.

Available fields for headers:

  • first_name

  • middle_name

  • last_name

  • email

  • phone

  • driver_license_number

  • driver_license_cats

  • driver_license_issue_date

  • driver_license_valid_till

  • hardware_key

  • address

  • lat

  • lng

  • radius

  • personnel_number

  • ssn

  • tracker_label

  • tags

  • undefined (if a meaning of a field is not known)

Required sub-user rights: employee_update.

Start employee import

post
/employee/import/start

Start the background process that imports employees from a preloaded TSV file, and return the process ID.

Create the file first with data/spreadsheet/parse, which converts a spreadsheet to TSV and returns its name as file_id. Pass that name here as filename.

Requires the employee_update right.

Authorizations
AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body
filenamestring · min: 1Required

Name of the server-side TSV file, as returned by data/spreadsheet/parse in its file_id. Must not be empty.

headersstring[] · min: 1Required

What each column of the file holds, in order. Must not be empty. Use undefined for a column whose meaning is not known.

user_headersstring[]Optional

Optional. Display labels for the columns. Must be the same length as headers.

Responses
200

The started import

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
idintegerOptional

ID of the created import process.

post/employee/import/start
POST /v2/employee/import/start HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "filename": "text",
  "headers": [
    "text"
  ],
  "user_headers": [
    "text"
  ]
}
{
  "success": true,
  "id": 1
}

Errors

These errors come in addition to the general error codes:

  • 15 - Too many requests (rate limit exceeded) - if too many imports in progress

  • 233 - No data file

  • 234 - Invalid data format

  • 247 - Entity already exists - there is another identical import with the same file

Read employee import

post
/employee/import/read

Return one employee import process by ID, including its progress.

The import process object is the same shape every import family returns, differing only in type, which is employee here.

Authorizations
AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body
process_idinteger · min: 1Required

ID of the import process.

Responses
200

The import process

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
post/employee/import/read
POST /v2/employee/import/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "process_id": 1
}
{
  "success": true,
  "value": {
    "id": 1,
    "user_id": 1,
    "subuser_id": 1,
    "created": "text",
    "type": "place",
    "params": {
      "headers": [
        "text"
      ],
      "user_headers": [
        "text"
      ]
    },
    "filename": "text",
    "status": "created",
    "status_change_date": "text",
    "progress": {
      "imported": 1,
      "failed": 1,
      "percent": null,
      "processed_lines": 1,
      "warnings": [
        {
          "line": 1,
          "message": "text"
        }
      ],
      "errors": [
        {
          "line": 1,
          "message": "text"
        }
      ]
    }
  }
}

Errors

These errors come in addition to the general error codes:

  • 201 - Not found in database (if import is not found)

List employee imports

post
/employee/import/list

List the current user's unfinished employee import processes.

Callable with an empty body.

Authorizations
AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Responses
200

Unfinished import processes

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
post/employee/import/list
POST /v2/employee/import/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "list": [
    {
      "id": 1,
      "user_id": 1,
      "subuser_id": 1,
      "created": "text",
      "type": "place",
      "params": {
        "headers": [
          "text"
        ],
        "user_headers": [
          "text"
        ]
      },
      "filename": "text",
      "status": "created",
      "status_change_date": "text",
      "progress": {
        "imported": 1,
        "failed": 1,
        "percent": null,
        "processed_lines": 1,
        "warnings": [
          {
            "line": 1,
            "message": "text"
          }
        ],
        "errors": [
          {
            "line": 1,
            "message": "text"
          }
        ]
      }
    }
  ]
}

Download failed employee rows

post
/employee/import/download_failed

Return a file of the rows that failed validation, so they can be corrected and imported again.

The response is the file itself, not a JSON envelope.

Authorizations
AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body
process_idinteger · min: 1Required

ID of the import process.

Responses
200

The failed rows as a file

text/tab-separated-values
string · binaryOptional
post/employee/import/download_failed
POST /v2/employee/import/download_failed HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "process_id": 1
}
binary

Errors

These errors come in addition to the general error codes:

  • 201 - Not found in database (if import is not found)

  • 204 - Entity not found (if file is not found)

PreviousEmployee avatar
NextForm

Last updated

Was this helpful?