Skip to main content
POST
Create or update a team

Restrictions

Usage

  • Omit team_id (or set it to 0) to create a team; pass an existing team_id to update it. A team_id that matches no team returns 400.
  • team_name must be unique among the account’s teams. A name used by another team returns 400, except when team_id is 0 and reset_if_name_exist is true — then that team is updated.
  • Membership is always replaced: the team’s members become exactly the union of person_ids, emails, and phones. Omitting all three on an update removes every member.
  • Entries that do not resolve to a member of the account (or the account owner) are silently dropped; nobody is invited.
  • On update, description and ref_id are overwritten as well — omitting them clears the stored values.
  • Updating also requires the caller to be a team member, the team creator, the account owner, or hold the Admin role.
  • Every call is recorded in the account audit log. Don’t put secrets in request fields.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Parameters for creating or updating a team.

team_name
string
required

Team display name. 1–39 characters.

Required string length: 1 - 39
team_id
integer<uint64>

ID of the team to update. Omit or set to 0 to create a new team; a non-zero ID must belong to an existing team of the account.

description
string

Free-form description, up to 500 characters. On update, omitting it clears the stored description.

Maximum string length: 500
person_ids
integer<uint64>[]

Person IDs to place in the team (member IDs, or the account ID for the account owner). Together with emails and phones they replace the entire member list; IDs that are not members of the account are ignored.

emails
string<email>[]

Emails of existing members to place in the team; merged with person_ids and phones. Addresses that match no member are ignored and no invitation is sent.

phones
string[]

Phone numbers of existing members to place in the team; merged with person_ids and emails. Numbers without a + prefix are parsed with countryCode; an unparseable number fails the whole request with 400, and numbers that match no member are ignored.

countryCode
string

Region hint for phones entries without a + prefix: an ISO 3166-1 alpha-2 code such as CN (the default when omitted) or a digit calling code such as 86.

ref_id
string

External reference ID (for example a department ID in an HR system), usable as a lookup key in POST /team/info and POST /team/delete. On update, omitting it clears the stored value.

reset_if_name_exist
boolean

When true and team_id is 0, an existing team with the same team_name is updated in place instead of returning a name-conflict error.

Response

Success

Success response envelope. On every 2xx response, request_id identifies the call (also mirrored in the Flashcat-Request-Id header) and data holds the endpoint-specific payload. Failure responses use a different shape — see ErrorResponse.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

Team create/update result.