Skip to main content

Public APIs - Manage employees

Overview

Use these public APIs to create, update, and delete employees in your Swif organization:

  • POST /restful/organization/employees

  • PUT /restful/organization/employees/:employeeId

  • DELETE /restful/organization/employees/:employeeId

  • You can also list your teams with GET /restful/organization/teams and filter GET /restful/organization/employees by team. See section 6.

  • GET /restful/organization/employees/:employeeId

These endpoints are designed for customer integrations (HRIS, IAM, internal tools) and complement the existing public GET /restful/organization/employees endpoint (paging employees).

You can find your API key here:
​Your API key token for Swif.ai | Help Center | Swif.ai

For general patterns and examples of using Swif APIs, see:
​APIs – Device and evidence retrieval | Help Center | Swif.ai

1. Base URL and authentication

Base URL

Use the correct domain for your tenant:

Example full URLs

Replace api.swifteam.com with api.eu.swifteam.com if your org is on the EU tenant.

Authentication

All endpoints use your organization public API token.

Headers

Authorization: Bearer <YOUR_ORG_PUBLIC_API_TOKEN> Content-Type: application/json Accept: application/json

If the token is missing, invalid, expired, or for another organization, the APIs return:

  • 401 Unauthorized or

  • 403 Forbidden

2. Create employee

Endpoint

POST /restful/organization/employees

Creates a new employee in your organization (same entity visible in the Swif Admin Console).

Request body

The payload must follow the employee model defined in the public Postman collection for these APIs.

  • You must provide all required fields (such as email, firstName, lastName, status, and any other required fields for your tenant).

  • Optional fields (e.g., identifiers, title, department, manager reference, dates, labels) can also be provided.

  • Unknown fields are rejected with clear validation errors (they are not silently ignored).

Example – minimal payload

{
  "email": "userA@example.com",
  "firstName": "User",
  "lastName": "Example",
  "status": "ACTIVE"
}

Example – extended payload (illustrative)

{
  "email": "userB@example.com",
  "firstName": "Alex",
  "lastName": "Doe",
  "status": "ACTIVE",
  "employeeId": "E-12345",
  "title": "Senior Engineer",
  "department": "Engineering",
  "managerId": "69a065901f00006c00210832",
  "startDate": "2024-01-15",
  "endDate": null,
  "labels": ["full-time", "remote-us"],
  "identifiers": {
    "hrisId": "HR-0001",
    "idpId": "00u1234567890abcDEF7"
  }
}

The exact field list, required fields, and enum values (e.g., valid status values) are defined in the latest Postman collection for these endpoints.

Response

  • Status: 201 Created (or 200 OK depending on spec)

  • Body: The created employee object, including the generated internal id:

{
  "id": "69a065901f00006c00210832",
  "email": "userB@example.com",
  "firstName": "Alex",
  "lastName": "Doe",
  "status": "ACTIVE"
  // ... other fields
}

Use this internal id in subsequent PUT and DELETE calls.

Validation and error handling

Typical behaviors:

  • Missing required field

    • Status: 400 Bad Request

    • Body: Error describing which field is missing or invalid.

    • No employee is created.

  • Duplicate unique value (e.g., email or unique employeeId)

    • Status: 400 or 409 Conflict

    • Body: Error indicating duplicate constraint (for example, “email already exists”).

    • No duplicate employee is created; the existing employee remains unchanged.

3. Update employee

Endpoint

PUT /restful/organization/employees/:employeeId

Updates an existing employee using the internal Swif employee id.

  • :employeeId is the internal id returned from POST /restful/organization/employees or retrieved via GET /restful/organization/employees.

  • It is not necessarily your HRIS or HR “employee number” (unless you map that into a custom field).

Request

PUT https://api.swifteam.com/restful/organization/employees/69a065901f00006c00210832
Authorization: Bearer <TOKEN>
Content-Type: application/json

The request body must follow the payload shape defined in the Postman collection for updateEmployeeForPartner. That contract also defines whether PUT is treated as:

  • Full replace – omitted optional fields may be cleared/reset, or

  • Partial update – omitted fields are left unchanged.

Example – update job details

{
  "title": "Staff Engineer",
  "department": "Platform Engineering",
  "status": "ACTIVE",
  "labels": ["full-time", "remote-us", "platform"]
}

Response

  • Status: 200 OK

  • Body: The full employee object as stored after the update.

Error behavior

  • Employee not found

    • Status: 404 Not Found

    • Body: Error such as "Employee not found".

    • No data is created or changed.

  • Validation errors

    • Status: 400 Bad Request

    • Body: Error describing invalid fields (e.g., invalid enum, malformed date, unknown field name).

Behavior for partial vs full update follows the updated contract used in testing (see Postman payload used in QA scenarios).

4. Delete employee

Endpoint

DELETE /restful/organization/employees/:employeeId

Deletes (or soft‑deletes, depending on implementation) an employee by internal id.

Request

DELETE https://api.swifteam.com/restful/organization/employees/69a065901f00006c00210832 Authorization: Bearer <TOKEN>

Response

  • Status: 204 No Content (or another success status defined in the spec)

  • Body: Empty.

After a successful delete:

  • The employee no longer appears in GET /restful/organization/employees results for your organization.

  • Internal tools (e.g., Employee Manager) show the employee as removed/soft‑deleted, depending on implementation.

Error behavior

  • Employee not found

    • Status: 404 Not Found (or equivalent)

    • Body: Error such as "Employee not found".

    • No side effects and no 500 error.

5. Read employees and IDs for use with PUT/DELETE

Use the public GET /restful/organization/employees endpoint to:

  • Confirm that a newly created employee appears in the list.

  • Retrieve the internal id to pass into:

    • PUT /restful/organization/employees/:employeeId

    • DELETE /restful/organization/employees/:employeeId

  • Verify that updates or deletes have taken effect.

  • For looking up one employee, check #8. Get an employee by ID.

6. Teams: list teams and filter employees by team

Every employee record includes the employee's primary team. You can also limit the employee list to one team. Requests that don't include teamId work exactly as before, so existing integrations don't need any changes.

How it works:

  1. Call GET /restful/organization/teams to get your team IDs.

  2. Add teamId=<id> to GET /restful/organization/employees.

List teams

Endpoint
​GET /restful/organization/teams

This returns your organization's active teams, sorted by name and then by ID. It doesn't take any parameters.

Request

curl --location 'https://api.swifteam.com/restful/organization/teams' \
--header 'Authorization: Bearer <YOUR_ORG_PUBLIC_API_TOKEN>'

Response

{
  "records": [
    { "teamId": "6667d7c93300001200972f03", "teamName": "Engineering" },
    { "teamId": "68a71f053000001f00873d00", "teamName": "Sales" }
  ],
  "meta": {
    "totalCount": 2,
    "resultCount": 2,
    "haveMore": false
  }
}

Field

Type

Description

teamId

string

The team's ID (24 hexadecimal characters)

teamName

string (optional)

The team's name

Filter employees by team

Endpoint
​GET /restful/organization/employees?teamId={Id}


​teamId is optional. You can still use q, offset (default 0) and limit (default 10) with it.

  • The filter only looks at each employee's primary team.

  • When you filter by team, the meta counts include only the matching employees.

Request

curl --location 'https://api.swifteam.com/restful/organization/employees?teamId=6667d7c93300001200972f03&offset=0&limit=10' \
--header 'Authorization: Bearer <YOUR_ORG_PUBLIC_API_TOKEN>'

Response

{
  "records": [
    {
      "id": "69a065901f00006c00210832",
      "firstName": "Alex",
      "lastName": "Doe",
      "emails": ["alex.doe@example.com"],
      "emailInfos": [
        { "value": "alex.doe@example.com", "type": "work", "primary": true }
      ],
      "department": "Engineering",
      "isActive": true,
      "relatedInfo": {
        "deleted": false,
        "status": "ACTIVE",
        "employmentType": "FULL_TIME",
        "source": "MANUAL"
      },
      "teamId": "6667d7c93300001200972f03",
      "teamName": "Engineering"
    }
  ],
  "meta": {
    "totalCount": 1,
    "resultCount": 1,
    "haveMore": false
  }
}

Team fields in employee records

GET /restful/organization/employees now returns two top-level fields in every record, whether or not you filter by team:

Field

Type

Description

teamId

string

ID of the employee's primary team

teamName

string (optional)

Name of that team. This can be missing for older records whose team is no longer active.

Errors

HTTP status

Code

When it happens

400

PUBLIC_API_INVALID_TEAM_ID

teamId is empty or isn't 24 hexadecimal characters

404

PUBLIC_API_TEAM_NOT_FOUND

The team doesn't exist, was deleted, or belongs to another organization. Message: "The team was not found in this organization."

Both errors include a friendlyMessage that you can show to users.

7. Assign employees to teams

You can set an employee's primary team when you create or update them.

  • teamId is optional on POST and PUT. If you send it, it must be the 24-character hexadecimal ID of an active team in your organization. Call GET /restful/organization/teams to get team IDs (see section 6).

  • Create and update responses include teamId and teamName. teamName may be missing if the team isn't active or has no name.

Create an employee in a team

POST /restful/organization/employees

If you…

Result

Leave out teamId

The employee goes to your organization's default team.

Send a valid teamId

The employee goes to that team.

Send "teamId": null

Error 400 PUBLIC_API_INVALID_TEAM_ID. null does not mean "use the default team." To use the default team, leave the field out.

curl --location 'https://api.swifteam.com/restful/organization/employees' \
--header 'Authorization: Bearer <YOUR_ORG_PUBLIC_API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "firstName": "Alex",
  "lastName": "Doe",
  "emails": ["alex.doe@example.com"],
  "teamId": "6667d7c93300001200972f03"
}'

Response: 200 OK with the created employee, including id, teamId and teamName.


Change an employee's team

PUT /restful/organization/employees/:employeeId

If you…

Result

Send a valid teamId

The employee's primary team changes to that team.

Leave out teamId

The employee stays in their current team.

curl --location --request PUT 'https://api.swifteam.com/restful/organization/employees/69a065901f00006c00210832' \
--header 'Authorization: Bearer <YOUR_ORG_PUBLIC_API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{ "teamId": "68a71f053000001f00873d00" }'

Response: 200 OK with the updated employee, including the new teamId and teamName.

Note: Changing an employee's team doesn't move their devices. Their devices stay in their current team and keep their policies.

8. Get an employee by ID

GET /restful/organization/employees/:employeeId

This returns one employee by their internal Swif id, including teamId and teamName.

curl --location 'https://api.swifteam.com/restful/organization/employees/69a065901f00006c00210832' \
--header 'Authorization: Bearer <YOUR_ORG_PUBLIC_API_TOKEN>'

Response: 200 OK with the employee record. teamName is included when the team is active and has a name.

Deleted employees and employees in other organizations aren't returned. Those requests get 404 EMPLOYEE_NOT_FOUND.

9. Team and employee ID errors

Errors come back in an errors array. Each entry has a type, a code and a friendlyMessage you can show to users.

{
  "errors": [
    {
      "type": "invalid_request_error",
      "code": "PUBLIC_API_INVALID_TEAM_ID",
      "friendlyMessage": "teamId must be a valid 24-character ID."
    }
  ]
}

HTTP status

Code

Endpoints

When it happens

400

PUBLIC_API_INVALID_TEAM_ID

POST, PUT

teamId is null, blank, not a string or not a 24-character hex ID

404

PUBLIC_API_TEAM_NOT_FOUND

POST, PUT

The team doesn't exist, was deleted or belongs to another organization

400

INVALID_EMPLOYEE_ID

GET, PUT

employeeId is malformed

404

EMPLOYEE_NOT_FOUND

GET, PUT

The employee doesn't exist, was deleted or belongs to another organization

When a team ID is rejected, no employee is created or changed.

Did this answer your question?

Related Articles

Swif Help Center
Swif.ai is the next generation of Mobile Device Management (MDM) software, with free Shadow IT for all of our customers included
IntercomWe run on Intercom