Use these public APIs to create, update, and delete employees in your Swif organization:
POST /restful/organization/employeesPUT /restful/organization/employees/:employeeIdDELETE /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:
Global tenant:
https://api.swifteam.comEU tenant:
https://api.eu.swifteam.com
Example full URLs
POST https://api.swifteam.com/restful/organization/employeesPUT https://api.swifteam.com/restful/organization/employees/:employeeIdDELETE https://api.swifteam.com/restful/organization/employees/:employeeId
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 Unauthorizedor403 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(or200 OKdepending 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 RequestBody: Error describing which field is missing or invalid.
No employee is created.
Duplicate unique value (e.g.,
emailor uniqueemployeeId)Status:
400or409 ConflictBody: 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.
:employeeIdis the internalidreturned fromPOST /restful/organization/employeesor retrieved viaGET /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 OKBody: The full employee object as stored after the update.
Error behavior
Employee not found
Status:
404 Not FoundBody: Error such as
"Employee not found".No data is created or changed.
Validation errors
Status:
400 Bad RequestBody: 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/employeesresults 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
idto pass into:PUT /restful/organization/employees/:employeeIdDELETE /restful/organization/employees/:employeeId
Verify that updates or deletes have taken effect.