Team Member Management API
The Team Member Management API allows you to manage team members and users in your TaskIP system. You can invite, read, update, and delete team members, as well as perform bulk deletes.
Resource IDs: The {id} segment of the team member routes only accepts digits. A non-numeric segment is a 404.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
GET | /api/public-v1/team-member | Get all team members |
POST | /api/public-v1/team-member | Invite a new team member |
GET | /api/public-v1/team-member/{id} | Get a specific team member |
PUT / PATCH | /api/public-v1/team-member/{id} | Update a team member |
DELETE | /api/public-v1/team-member/{id} | Delete a team member |
POST | /api/public-v1/team-member/bulk-delete | Delete multiple team members |
Get All Team Members
Retrieve a list of all team members in your system.
GET /api/public-v1/team-memberRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination (default: 1) |
item | integer | No | Team members per page (default: 10). Use 0 to return all team members without pagination |
search | string | No | Search by name or email |
active_only | boolean | No | When true, only active members are returned |
Users of type contact (clients) are never included. Results are ordered by id descending.
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/team-member?page=1&item=20&search=john" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"JavaScript Example
const response = await fetch('https://public-api.taskip.net/api/public-v1/team-member?active_only=1', {
method: 'GET',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
}
});
const teamMembers = await response.json();Example Response
{
"message": "Team member list",
"data": [
{
"id": 26,
"first_name": "Alice",
"last_name": "Johnson",
"full_name": "Alice Johnson",
"position": "Frontend Developer",
"email": "alice.johnson@taskip.com",
"uuid": "550e8400-e29b-41d4-a716-446655440026",
"role": {
"user_id": 26,
"role_id": 3,
"role_details": {
"id": 3,
"name": "Member",
"status": 1,
"tenant_id": null
}
},
"is_owner": false,
"created_at": "25, Jan, 2024",
"teams": [
{
"id": 1,
"name": "Development Team",
"department": { "id": 2, "name": "Engineering", "status": 1 },
"members": [
{ "id": 26, "name": "Alice Johnson", "email": "alice.johnson@taskip.com", "image": null }
],
"description": "Frontend and Backend Development",
"created_at": "10 Jan, 2024"
}
],
"image": null,
"invitation": {
"invited_at": "25,Jan,2024 11:45:00",
"last_sent_at": "25,Jan,2024 11:45:00",
"accepted_at": null,
"expires_at": "27,Jan,2024 11:45:00",
"status": "pending",
"invitation_status": "pending",
"can_reinvite": false,
"can_invite_now": false,
"cooldown": {
"last_sent_at": "2024-01-25T11:45:00+00:00",
"can_resend_at": "2024-01-25T11:50:00+00:00",
"remaining_seconds": 240
}
},
"invitation_status": "pending",
"tasks": [],
"is_on_vacation": false,
"is_active": false
}
],
"links": {
"first": "https://public-api.taskip.net/api/public-v1/team-member?page=1",
"last": "https://public-api.taskip.net/api/public-v1/team-member?page=3",
"prev": null,
"next": "https://public-api.taskip.net/api/public-v1/team-member?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"path": "https://public-api.taskip.net/api/public-v1/team-member",
"per_page": 20,
"to": 20,
"total": 45
}
}When search is supplied, meta.search echoes the search term. When item=0, the response contains only message and data.
Create a Team Member
Invite a new team member to your workspace. The member is created with a pending invitation and, unless send_invite is false, an invitation email is sent immediately.
POST /api/public-v1/team-memberRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Team member’s email address (must pass DNS validation). Must not already belong to a client, lead, or another account in this workspace |
first_name | string | Yes | First name (max 191 characters). Markup and characters other than letters, spaces, apostrophes, hyphens and dots are stripped |
last_name | string | Yes | Last name (max 191 characters). Sanitized the same way as first_name |
position | string | No | Job position/title (max 191 characters) |
role_id | integer | Yes | Role ID, see Roles |
team_ids | array | No | Array of team IDs to add the member to |
image | integer | No | Image/avatar media upload ID |
send_invite | boolean | No | Send the invitation email now (default: true). When false the member is created without an email being sent |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/team-member" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"email": "alice.johnson@taskip.com",
"first_name": "Alice",
"last_name": "Johnson",
"position": "Frontend Developer",
"role_id": 3,
"team_ids": [1]
}'Python Example
import requests
headers = {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
}
team_member_data = {
"email": "alice.johnson@taskip.com",
"first_name": "Alice",
"last_name": "Johnson",
"position": "Frontend Developer",
"role_id": 3,
"team_ids": [1]
}
response = requests.post(
'https://public-api.taskip.net/api/public-v1/team-member',
headers=headers,
json=team_member_data
)
result = response.json()Example Response
{
"msg": "Team Member Invited Successfully",
"data": {
"id": 26,
"first_name": "Alice",
"last_name": "Johnson",
"full_name": "Alice Johnson",
"position": "Frontend Developer",
"email": "alice.johnson@taskip.com",
"uuid": "550e8400-e29b-41d4-a716-446655440026",
"role": {
"user_id": 26,
"role_id": 3,
"role_details": {
"id": 3,
"name": "Member",
"status": 1,
"tenant_id": null
}
},
"is_owner": false,
"created_at": "25, Jan, 2024",
"teams": [
{
"id": 1,
"name": "Development Team",
"department": { "id": 2, "name": "Engineering", "status": 1 },
"members": [
{ "id": 26, "name": "Alice Johnson", "email": "alice.johnson@taskip.com", "image": null }
],
"description": "Frontend and Backend Development",
"created_at": "10 Jan, 2024"
}
],
"image": null,
"invitation": {
"invited_at": "25,Jan,2024 11:45:00",
"last_sent_at": "25,Jan,2024 11:45:00",
"accepted_at": null,
"expires_at": "27,Jan,2024 11:45:00",
"status": "pending",
"invitation_status": "pending",
"can_reinvite": false,
"can_invite_now": false,
"cooldown": {
"last_sent_at": "2024-01-25T11:45:00+00:00",
"can_resend_at": "2024-01-25T11:50:00+00:00",
"remaining_seconds": 240
}
},
"invitation_status": "pending",
"tasks": [],
"is_on_vacation": false,
"is_active": false
}
}If your plan’s team member limit has been reached, or the email already belongs to an active member of this workspace, the API returns 422 with {"error": {"msg": ["..."]}}.
Get a Specific Team Member
Retrieve details of a specific team member by ID.
GET /api/public-v1/team-member/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Team member ID (digits only) |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/team-member/26" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"message": "Team Member Details",
"data": {
"id": 26,
"first_name": "Alice",
"last_name": "Johnson",
"full_name": "Alice Johnson",
"position": "Frontend Developer",
"email": "alice.johnson@taskip.com",
"uuid": "550e8400-e29b-41d4-a716-446655440026",
"role": {
"user_id": 26,
"role_id": 3,
"role_details": {
"id": 3,
"name": "Member",
"status": 1,
"tenant_id": null
}
},
"is_owner": false,
"created_at": "25, Jan, 2024",
"teams": [
{
"id": 1,
"name": "Development Team",
"department": { "id": 2, "name": "Engineering", "status": 1 },
"members": [
{ "id": 26, "name": "Alice Johnson", "email": "alice.johnson@taskip.com", "image": null }
],
"description": "Frontend and Backend Development",
"created_at": "10 Jan, 2024"
}
],
"image": null,
"invitation": {
"invited_at": "25,Jan,2024 11:45:00",
"last_sent_at": "25,Jan,2024 11:45:00",
"accepted_at": null,
"expires_at": "27,Jan,2024 11:45:00",
"status": "pending",
"invitation_status": "pending",
"can_reinvite": false,
"can_invite_now": false,
"cooldown": {
"last_sent_at": "2024-01-25T11:45:00+00:00",
"can_resend_at": "2024-01-25T11:50:00+00:00",
"remaining_seconds": 240
}
},
"invitation_status": "pending",
"tasks": [],
"is_on_vacation": false,
"is_active": false
}
}If no team member has that ID, the API returns 404.
Update a Team Member
Update an existing team member’s information.
PUT /api/public-v1/team-member/{id}
PATCH /api/public-v1/team-member/{id}PUT and PATCH are handled identically. The {id} is the numeric team member (user) ID. The caller needs the teams edit permission, and the permission rules in Permissions and Role Rules apply.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Team member ID to update (digits only) |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
first_name | string | Yes | Max 191 characters. HTML and characters other than letters, spaces, apostrophes, hyphens and periods are stripped |
last_name | string | Yes | Max 191 characters, sanitized the same way |
role_id | integer | Yes | See Roles. You cannot assign a role above your own |
email | string | No | Valid email. Must not belong to another user, lead or contact; the member being edited is excluded from that check, so re-sending their current email is fine. When omitted or null, the stored email is kept |
position | string | No | Max 191 characters. Partial: when omitted, the stored position is kept; send null or an empty value to clear it |
team_ids | array | No | When non-empty, replaces the member’s current team memberships |
image | integer | No | ID of an existing media upload. When it matches, replaces the member’s current image |
send_invite has no effect on update.
Example Request
curl -X PUT "https://public-api.taskip.net/api/public-v1/team-member/26" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"email": "alice.johnson@company.com",
"first_name": "Alice",
"last_name": "Johnson",
"position": "Lead Frontend Developer",
"role_id": 3,
"team_ids": [1],
"image": 150
}'Example Response
{
"msg": "Team Member updated successfully"
}A rejected update (permission rules, validation) returns 422 with {"error": {"msg": ["..."]}} or field errors. An unknown ID returns 404.
Delete a Team Member
Delete a specific team member from your system.
DELETE /api/public-v1/team-member/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Team member ID to delete (digits only) |
Warning: Deleting a team member revokes their workspace access and removes their image and team memberships. This action cannot be undone. The caller needs the teams delete permission, and the permission rules apply.
Example Request
curl -X DELETE "https://public-api.taskip.net/api/public-v1/team-member/26" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"msg": "Team member access revoked successfully"
}If no user has that ID, the API returns 404 with {"msg": "Team Member not found"}. The workspace owner cannot be removed (422).
Bulk Delete Team Members
Delete multiple team members at once. The caller needs the teams delete permission. The whole batch is checked first: if any member is one the caller may not act on, or is the workspace owner, nothing is deleted and 422 is returned.
POST /api/public-v1/team-member/bulk-deleteRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
ids | array | Yes | Array of team member IDs to delete (max 1000 items) |
ids.* | integer | Yes | Each ID must be an integer that exists in the users table |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/team-member/bulk-delete" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"ids": [24, 25, 27, 28]
}'JavaScript Example
const bulkDeleteData = {
ids: [24, 25, 27, 28]
};
const response = await fetch('https://public-api.taskip.net/api/public-v1/team-member/bulk-delete', {
method: 'POST',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
},
body: JSON.stringify(bulkDeleteData)
});
const result = await response.json();Example Response
{
"msg": "Team members access revoked successfully"
}If none of the IDs match a team member, the API returns 404 with {"msg": "Team Member not found"}.
Permissions and Role Rules
Update, delete and bulk delete share these rules:
- The caller needs the
teamsedit (update) or delete (delete, bulk delete) permission. - Administrators can only be modified or removed by an Administrator; Managers only by an Administrator or Manager.
- The workspace owner can only be modified by themselves, cannot be removed, and cannot be demoted from Administrator.
- A role cannot assign a role above its own (see Roles).
Roles
role_id must be an integer. The built-in role IDs are listed below.
role_id | Role | Notes |
|---|---|---|
1 | Administrator | Can only be assigned by the workspace owner |
2 | Manager | Can only be assigned by an Administrator or Manager |
3 | Member | |
4 | Client |
Error Responses
Common Error Codes
| Status Code | Error Type | Description |
|---|---|---|
401 | Unauthorized | Invalid or missing X-Secret-Key |
404 | Not Found | A non-numeric ID in the path, or an unknown team member ID (show, delete, bulk delete) |
422 | Validation Error | Request data failed validation, or the operation was rejected (plan limit, insufficient permission or role, workspace owner protection) |
429 | Too Many Requests | Rate limit exceeded |
Example Error Response
Validation failures return 422 with the failing fields under error:
{
"error": {
"email": ["The email field is required."],
"role_id": ["You are not allowed to assign the Administrator role."]
}
}Response Schemas
Team Member Object
{
"id": "integer",
"first_name": "string",
"last_name": "string",
"full_name": "string",
"position": "string|null",
"email": "string",
"uuid": "string",
"role": "object ({user_id, role_id, role_details})",
"is_owner": "boolean",
"created_at": "string (formatted: 'd, M, Y')",
"teams": "array",
"image": "object|null",
"invitation": "object",
"invitation_status": "string (not_invited | pending | expired | accepted)",
"tasks": "array",
"is_on_vacation": "boolean",
"is_active": "boolean"
}Team Object
{
"id": "integer",
"name": "string",
"department": "object ({id, name, status})",
"members": "array of {id, name, email, image}",
"description": "string|null",
"created_at": "string (formatted: 'd M, Y')"
}Image Object
{
"id": "integer",
"title": "string",
"ext": "string",
"size": "integer",
"url": "string|null",
"media_type": "string",
"createdAt": "string (d-m-Y h:i:s)"
}Invitation Object
{
"invited_at": "string (d,M,Y h:i:s)",
"last_sent_at": "string|null",
"accepted_at": "string|null",
"expires_at": "string|null",
"status": "string (pending | expired | accepted)",
"invitation_status": "string (not_invited | pending | expired | accepted)",
"can_reinvite": "boolean",
"can_invite_now": "boolean",
"cooldown": "object|null ({last_sent_at, can_resend_at, remaining_seconds})"
}Best Practices
Team Management
- Role Assignment: Assign appropriate roles based on job functions
- Regular Reviews: Periodically review team member access
- Deferred invites: Use
send_invite: falseto create members now and send the invitation later
User Onboarding
- Welcome Emails: Use invitation emails for new team members
- Profile Completion: Encourage complete profile setup
- Access Reviews: Regular access reviews and updates
Tip: Use active_only=1 on the GET /team-member endpoint to build member pickers that exclude people who have not yet accepted their invitation.