POST /v1/employees/imports — Import Employees

Send Honestly the employees you want it to hold. Each request is a complete snapshot of your active workforce: employees you send are created or updated, and employees you stop sending are offboarded. This endpoint replaces the CSV-over-SFTP import. Because JSON carries structure per employee rather than one header row per file, you can decide field by field and employee by employee what an import should change — including leaving a field exactly as an admin configured it in the app.

This is the only write endpoint in the API. Every other endpoint in this reference is a read-only GET, and the API key you use for those will not work here — see Authentication below.

This request can set each employee’s role and data access, so the key you use here can change who administers your account. Treat it as a privileged credential: keep it in the system that owns your HR data, never share it with reporting or BI tools, and rotate it from the Integrations page if it is ever exposed.

Endpoint

POST https://api.honestly.com/v1/employees/imports

Authentication

Authenticate with your API key in the X-Api-Key header, as everywhere else in this API. The key must carry the employees:write scope. Keys created on the API keys page are read-only and are rejected here with 403. The key for this endpoint is issued separately, when you connect the REST API integration on the Integrations page.

How an Import Is Applied

Honestly validates the request

The whole body is checked against the schema below. If anything is malformed you get a 400 and nothing is queued.

You get a 202 and an import id

A workforce import is far too much work for one HTTP request, so it runs in the background. The response confirms the import was accepted, not that it finished.

Honestly reconciles your account

Employees are created and updated one by one, supervisors are resolved once every employee has been applied, and anyone this API created but you no longer send is offboarded.

The result of an import appears on the Integrations page in the app, and account admins are emailed if any employee was skipped. There is no endpoint to poll for the outcome, so import_uuid is a reference for support rather than something to check.

Omitted, Null, and a Value

This is the part worth reading twice. Every optional property has three distinguishable states, and the difference between the first two is the difference between preserving a field and wiping it.

You send	Meaning
The property is absent	Leave it unchanged. Honestly holds no opinion from this import, so whatever the value is today survives — including something an admin set in the app.
`"property": null`	Clear it, or reset it to its default.
`"property": "value"`	Overwrite it with what you sent.

attributes follows the same rule per entry, with membership of the list standing in for the property being present:

"attributes": [
  { "name": "Location",    "value": null },
  { "name": "Cost Center", "value": { "name": "CC-4120" } }
]

Location is cleared, Cost Center is set, and any attribute not in the list — Department, say — is left exactly as it is. An empty list therefore means “I have nothing to say about this employee’s attributes”, not “remove them all”.

Porting a CSV export? A file that emits a fixed header and blanks for missing data is, in JSON terms, sending null everywhere. If you translate such an export literally you will clear fields the file was only ever silent about. Send a property only when your HR system actually has an opinion about it.

Body Parameters

object[]

required

The complete set of employees to hold for this account. At least one.There is deliberately no limit on how many employees you send: reconciliation is only sound when one request carries your whole workforce, so an account of any size sends a single request. The only ceiling is the request body size we accept. Payloads of this shape compress extremely well, since most of their bytes are repeated attribute names — send Content-Encoding: gzip.

Show employee

string

required

Your stable identifier for this employee, from your HR system. Honestly matches employees on this, so it must be unique within the request and must not change between imports.

string

required

Must be unique within your account. If the address already belongs to a different employee, this one is skipped.

string

required

The employee’s first name. Note there is no underscore in the property name — it matches the CSV header.

string

required

The employee’s last name.

string

ISO 639-1 code, two letters. Falls back to the default language configured on the integration. An unsupported code skips this employee rather than failing the import.

string | null

The import_id of this employee’s supervisor. Resolved after every employee in the request has been applied, so the order you send them in does not matter. null removes the supervisor.

string | null

What this employee can do in Honestly. One of Admin, Manager, Analyst, Report viewer or Respondee. null resets them to Respondee, which clears their data-access grants with it.Anything else — including legacy spellings the CSV import tolerates — is refused and that employee is skipped.

object | null

Which data this employee may see in reports. null revokes every grant. Permissions only mean something for roles that can log in; for a Respondee they are ignored.

Show permissions

boolean

default:"false"

Access to all data. When true, grants is ignored entirely.

object[]

Scoped grants, each naming an attribute and one of its values. Send as many as you need — there is no limit, and they may name different attributes. An empty list with all_data: false revokes every grant.How several grants combine depends on whether they name the same attribute:

Several values of one attribute widen the scope. Department: Sales plus Department: Marketing lets this employee see both departments.
Grants on different attributes narrow it. Department: Sales plus Location: Berlin does not mean “all of Sales, plus all of Berlin” — it means the Berlin part of Sales only. Honestly intersects across attributes, so the employee sees the people who match every attribute you granted.

"grants": [
  { "attribute": { "name": "Department" }, "value": { "name": "Sales" } },
  { "attribute": { "name": "Department" }, "value": { "name": "Marketing" } },
  { "attribute": { "name": "Location" },   "value": { "name": "Berlin" } }
]

That grants Sales or Marketing, and Berlin — a Berlin-based lead over both teams.A grant naming an attribute or value that does not exist in your account is dropped, and the employee is imported regardless. Because attributes intersect, dropping one silently widens the scope rather than narrowing it — check the names against the Attributes endpoint if a grant does not behave as you expect.

object[]

Employee attributes, each naming an attribute and the value assigned to it. See Omitted, null, and a value for how membership of this list decides what changes.Attribute names are matched loosely — case and surrounding whitespace are normalised, so age category and Age Category are the same attribute. Listing the same attribute twice for one employee is refused and that employee is skipped.Attributes and attribute values that do not exist yet are created, so opening a Munich office and sending Location → München needs no preparation in the app.

Show attribute

string

required

The attribute name as it appears in the app.

object | null

required

null clears the assignment. Omit the whole entry to leave it unchanged.

Show value

string

required

The value assigned to the attribute.

Age Category and Seniority

Two attribute names are special, because Honestly stores a bucket rather than what you send. Send the year — not a date, and not the bucket.

Attribute	Send	Stored as
`Age Category`	The birth year, exactly four digits: `"1985"`	`< 20`, `20-29`, `30-39`, `40-49`, `50-59`, `60+`
`Seniority`	The year the employee joined, exactly four digits: `"2019"`	`< 5`, `05-09`, `10-14`, … `45+`

The bucket is derived at import time, which means these two drift as people age and accrue tenure. Sending the same year on every import is correct and intended — it is what keeps the bucket current. A value that is not exactly four digits skips that employee.

Offboarding

An employee this API created and you stop sending is offboarded on the next import. Employees created any other way — in the app, by a file upload, over SFTP, or by an HCM connector — are never touched by this endpoint. To protect you against a broken export, an import that would offboard more than the deletion threshold configured on the integration is cancelled in full and changes nothing at all. The threshold defaults to 20% of the employees this API manages, and you can change it in the REST API dialog on the Integrations page. Raise it deliberately for a planned mass offboarding, then set it back. The guard does not apply when nothing would be offboarded, so your first import into an empty account is never blocked.

Example Request

curl -X POST "https://api.honestly.com/v1/employees/imports" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @workforce.json

With workforce.json:

{
  "employees": [
    {
      "import_id": "HR-10045",
      "email": "marlene.faber@example.com",
      "firstname": "Marlene",
      "lastname": "Faber",
      "language": "de",
      "reports_to_id": "HR-10002",
      "role": "Manager",
      "permissions": {
        "all_data": false,
        "grants": [
          { "attribute": { "name": "Department" }, "value": { "name": "Customer Success" } }
        ]
      },
      "attributes": [
        { "name": "Department",   "value": { "name": "Customer Success" } },
        { "name": "Location",     "value": { "name": "Berlin" } },
        { "name": "Age Category", "value": { "name": "1988" } },
        { "name": "Seniority",    "value": { "name": "2019" } }
      ]
    },
    {
      "import_id": "HR-10046",
      "email": "tom.kessler@example.com",
      "firstname": "Tom",
      "lastname": "Kessler",
      "reports_to_id": "HR-10002",
      "attributes": [
        { "name": "Department", "value": { "name": "Customer Success" } }
      ]
    },
    {
      "import_id": "HR-10002",
      "email": "iris.nowak@example.com",
      "firstname": "Iris",
      "lastname": "Nowak",
      "reports_to_id": null,
      "role": null,
      "attributes": [
        { "name": "Department", "value": { "name": "Operations" } },
        { "name": "Location",   "value": null }
      ]
    }
  ]
}

The three employees exercise different parts of the contract. Marlene is a full record. Tom sends no role and no permissions, so whatever an admin configured for him in the app stays exactly as it is. Iris left the management track: her supervisor and role are reset, her Location is cleared, and her Age Category is untouched because it is not in her list.

Example Response

{
  "import_uuid": "e665fc97-2ead-4800-9a7b-f531131acda4"
}

string

Identifier of the queued import, returned with 202 Accepted. Keep it if you need to reference the import when contacting support.

Errors

Status code	Meaning
`400 Bad Request`	The body is malformed — invalid JSON, an unknown property, a wrong type, or a missing required property.
`401 Unauthorized`	The `X-Api-Key` header is missing or the key is not valid.
`403 Forbidden`	The key is valid but does not carry the `employees:write` scope. Read-only keys from the API keys page land here.
`404 Not Found`	The REST API integration is not connected for this account.
`409 Conflict`	An import for this account is still running. Wait for it to finish before sending another.
`500 Internal Server Error`	Something went wrong on our side.

Errors use the same envelope as the rest of the API — see Error handling.

When One Employee Is Refused

Some problems affect a single employee rather than the whole request. That employee is skipped, the rest of the import is applied, and account admins are emailed a summary. An employee is skipped when:

their role is not one of the five accepted values
their language is not a valid ISO 639-1 code
their Age Category or Seniority is not exactly four digits
they list the same attribute twice
their email already belongs to somebody else

A skipped employee still counts as present, so reconciliation will not offboard them — they are simply left as they were. Two problems cancel the entire import instead, because the result would otherwise depend on the order of your list: an employee with a missing or empty import_id, and the same import_id appearing twice.

​Endpoint

​Authentication

​How an Import Is Applied

​Omitted, Null, and a Value

​Body Parameters

​Age Category and Seniority

​Offboarding

​Example Request

​Example Response

​Errors

​When One Employee Is Refused

Endpoint

Authentication

How an Import Is Applied

Omitted, Null, and a Value

Body Parameters

Age Category and Seniority

Offboarding

Example Request

Example Response

Errors

When One Employee Is Refused