Teams

Organize users, campaigns, workflows, and advocacy boards into teams for better access control and management.

Teams enable you to organize your Oktopost account by grouping users and resources together. By assigning entities to teams, you can control access, segment reporting, and manage permissions at scale. Teams can contain users, campaigns, workflows, and advocacy boards.

Team assignments control which users can access specific campaigns, workflows, and advocacy boards. Use teams to implement role-based access control across your organization.

Team-Bound Entities

The following entity types can be assigned to teams:

Users - Control which team members have access to specific resources
Campaigns - Organize campaigns by team, region, or product line
Workflows - Assign approval workflows to specific teams
Advocacy Boards - Segment employee advocacy programs by team or department

Get Team

Retrieve details for a specific team by ID.

Request

curl -i https://api.oktopost.com/v2/team/025000000000000

Response

{
    "Result": true,
    "Team": {
        "Id": "025000000000000",
        "Created": "2019-09-24 22:11:36",
        "Modified": "2019-09-24 22:11:40",
        "Name": "US East"
    }
}

List Teams

Retrieve all teams in your account.

Request

curl -i https://api.oktopost.com/v2/team

Response

{
    "Result": true,
    "Items": [
        {
            "Id": "025000000000000",
            "Created": "2019-09-24 22:11:36",
            "Modified": "2019-09-24 22:11:40",
            "Name": "US East"
        },
        {
            "Id": "025000000000001",
            "Created": "2019-09-24 22:15:20",
            "Modified": "2019-09-24 22:15:20",
            "Name": "US West"
        }
    ],
    "Total": 2
}

Create Team

Create a new team in your account.

Parameters

Parameter	Type	Required	Description
name	String	Yes	The team name

Request

curl -i https://api.oktopost.com/v2/team -X POST \
  -d name="US West"

Response

{
    "Result": true,
    "Team": {
        "Id": "025000000000000",
        "Created": "2020-04-24 12:11:36",
        "Modified": "2020-04-24 12:11:40",
        "Name": "US West"
    }
}

Update Team

Modify an existing team's properties.

Parameters

Parameter	Type	Required	Description
name	String	Yes	The updated team name

Request

curl -i https://api.oktopost.com/v2/team/025000000000000 -X POST \
  -d name="US South"

Response

{
    "Result": true,
    "Team": {
        "Id": "025000000000000",
        "Created": "2020-04-24 12:11:36",
        "Modified": "2020-04-24 12:12:59",
        "Name": "US South"
    }
}

Delete Team

Remove a team from your account.

Deleting a team removes team assignments from all associated entities (users, campaigns, workflows, boards). This action cannot be undone.

Request

curl -i https://api.oktopost.com/v2/team/025000000000000 -X DELETE

Response

{
    "Result": true
}

List Teams for an Entity

Retrieve all teams assigned to a specific entity (user, campaign, workflow, or advocacy board).

This endpoint is limited to 1,000 results and pagination is not available.

Request

curl -i https://api.oktopost.com/v2/team-entity/002000000000000

Response

{
    "Result": true,
    "Items": [
        {
            "Id": "025000000000000",
            "Created": "2019-09-24 22:11:36",
            "Modified": "2019-09-24 22:11:40",
            "Name": "US East"
        },
        {
            "Id": "025000000000001",
            "Created": "2019-09-24 22:15:20",
            "Modified": "2019-09-24 22:15:20",
            "Name": "US West"
        }
    ]
}

Add Teams to an Entity

Assign one or more teams to an entity (user, campaign, workflow, or advocacy board).

Parameters

Parameter	Type	Required	Description
teamIds	String	Yes	Comma-separated list of team IDs to assign to the entity

Request

curl -i https://api.oktopost.com/v2/team-entity/002000000000000 -X POST \
  -d teamIds="025000000000000,025000000000001"

Response

{
    "Result": true
}

Remove Teams from an Entity

Remove one or more team assignments from an entity.

Parameters

Parameter	Type	Required	Description
teamIds	String	Yes	Comma-separated list of team IDs to remove from the entity

Request

curl -i https://api.oktopost.com/v2/team-entity/002000000000000 -X DELETE \
  -d teamIds="025000000000000,025000000000001"

Response

{
    "Result": true
}

Understanding Entity IDs

When working with team-entity endpoints, the entity ID in the URL determines which resource you're managing teams for:

User ID (starts with 00A) - Manage team assignments for a user
Campaign ID (starts with 002) - Manage team assignments for a campaign
Workflow ID (starts with cwf) - Manage team assignments for a workflow
Board ID (starts with brd) - Manage team assignments for an advocacy board

Example: Assigning Teams to a Campaign

# Campaign ID: 002000000000000
curl -i https://api.oktopost.com/v2/team-entity/002000000000000 -X POST \
  -d teamIds="025000000000000,025000000000001"

Example: Checking User Team Assignments

# User ID: 00A000000000000
curl -i https://api.oktopost.com/v2/team-entity/00A000000000000

Use Cases

Organize by Region

Create teams for different geographic regions and assign users and campaigns accordingly:

# Create regional teams
curl -i https://api.oktopost.com/v2/team -X POST \
  -d name="North America"

curl -i https://api.oktopost.com/v2/team -X POST \
  -d name="EMEA"

# Assign campaigns to regional teams
curl -i https://api.oktopost.com/v2/team-entity/002000000000001 -X POST \
  -d teamIds="025000000000000"

Department-Based Access Control

Segment resources by department to control access:

# Assign workflows to marketing team
curl -i https://api.oktopost.com/v2/team-entity/cwf000000000000 -X POST \
  -d teamIds="025000000000001"

# Assign advocacy board to HR team
curl -i https://api.oktopost.com/v2/team-entity/brd000000000000 -X POST \
  -d teamIds="025000000000002"

Multi-Team Assignments

Assign an entity to multiple teams for cross-functional access:

# Assign campaign to both marketing and sales teams
curl -i https://api.oktopost.com/v2/team-entity/002000000000000 -X POST \
  -d teamIds="025000000000001,025000000000002"

Best Practices

Team Structure

Keep team names descriptive - Use clear names like "Marketing - North America" instead of abbreviations
Plan your hierarchy - Consider how teams map to your organizational structure
Limit team count - Too many teams can complicate management; consolidate where possible

Access Control

Assign users to appropriate teams - Ensure users have access to the resources they need
Review team assignments regularly - Audit team memberships quarterly
Use teams for workflows - Route approval workflows to specific teams for better organization

Entity Management

Bulk operations - Use comma-separated team IDs to assign multiple teams at once
Check before deleting - List entity teams before removing assignments
Document team purposes - Maintain documentation of what each team represents

Users - Manage user accounts and assign them to teams
Campaigns - Create campaigns and assign them to teams
Workflows - Set up approval workflows for specific teams
Advocacy Boards - Organize employee advocacy by team

Teams provide the foundation for access control and resource organization in Oktopost. Use them strategically to create clear boundaries and enable effective collaboration across your organization.

On this page