> ## Documentation Index > Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a team > Creates a new team. Requires an admin user. Create a team (admin) **Permission:** Org **admin** only. Denials read `Manage Teams`. **Not callable with an API key.** Requires an org **admin**. Service accounts cannot be assigned the admin role and their role cannot be changed, so every API key gets `403`. Only a signed-in admin can call it. ## OpenAPI ````yaml /api-reference/specs/teams.json post /api/teams openapi: 3.1.0 info: title: ConveYour API — Teams description: >- Create and manage teams — organizational units that partition contacts, content, and users for scoped access. version: 1.0.0 servers: - url: https://{subdomain}.conveyour.com description: Your organization's ConveYour instance variables: subdomain: default: acme description: >- Your organization's slug — the subdomain you sign in on. Replace `acme` with yours: if you sign in at `bigco.conveyour.com`, enter `bigco`. security: - conveyourToken: [] tags: - name: Teams description: >- Create and manage teams — organizational units that partition contacts, content, and users for scoped access. paths: /api/teams: post: tags: - Teams summary: Create a team description: >- Creates a new team. Requires an admin user. Create a team (admin) **Permission:** Org **admin** only. Denials read `Manage Teams`. **Not callable with an API key.** Requires an org **admin**. Service accounts cannot be assigned the admin role and their role cannot be changed, so every API key gets `403`. Only a signed-in admin can call it. operationId: createATeamAdmin parameters: - $ref: '#/components/parameters/teams' requestBody: required: true content: application/json: schema: type: object required: - label - name properties: label: description: Human-readable team name. Must be unique within the org. type: string name: description: >- Machine name for the team. Must be unique within the org and use tag format (no spaces). type: string filters: description: >- Contact filter definition that restricts which contacts are visible to team members. type: object additionalProperties: true contact_fields: description: >- List of contact fields shown for team contacts. Each entry references a contact field. type: array items: type: string color: description: Display color for the team. type: string sms_autoreply: description: SMS auto-reply message for the team. type: string block_sms: description: When true, blocks SMS for the team. type: boolean portal_new_conversation: description: >- Allow team members to start new conversations from the portal. type: boolean contact_desc: description: >- Liquid template producing a short summary description for each team contact. type: string sendblue_number: description: SendBlue phone number used for team SMS routing. type: string responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: $ref: '#/components/schemas/Team' example: status: ok message: Team record created data: id: 64a1b2c3d4e5f6a7b8c9d0e1 label: West Region name: west_region color: '#3366ff' twilio_phone: '' '403': $ref: '#/components/responses/Forbidden' '429': description: >- Too many requests — plan quota exhausted. Applies to **POST only**. `data` carries the usage overview for the `teams` limit (used / unused / overage) so you can show what was hit. content: application/json: schema: type: object properties: status: type: string enum: - failed description: Always `failed`. message: type: string description: Human-readable explanation. data: type: object description: >- Usage overview for the limit that was hit — used, unused and overage counts. components: parameters: teams: name: teams[] in: query description: >- Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so `teams=A&teams=B` silently resolves to B alone. On requests with a JSON body you may send `teams` (no brackets) in the body instead. **Values that are not valid ObjectIds are silently ignored** — a mistyped team ID behaves as if no team was sent. See the [teams section of the API conventions guide](/guides/api-conventions#team-scoping). style: form explode: true schema: type: array items: type: string example: - 64a1b2c3d4e5f6a7b8c9d0ff schemas: Envelope: type: object description: The common response envelope shared by all ConveYour endpoints. properties: status: type: string enum: - ok - failed description: '`ok` on success, `failed` on error.' message: type: string description: Human-readable description of the result. data: description: >- The response payload — an object or an array depending on the endpoint. Team: type: object description: A team. Fields are. properties: id: type: string description: Team ID. org_id: type: integer description: Owning organization. name: type: string description: Machine-readable team name. label: type: string description: Display label. color: type: string description: UI colour. filters: type: object description: Contact filter defining team membership. contact_fields: type: object description: Contact fields scoped to this team. contact_field: type: array description: Contact field references. contact_desc: type: string description: Contact description template. model: type: array description: Associated models. twilio_phone: type: string description: Team sending number. twilio_ms_id: type: string description: Twilio messaging service ID. sendblue_number: type: string description: Sendblue number, when that integration is used. sms_autoreply: type: string description: Automatic SMS reply text. block_sms: type: boolean description: Whether outbound SMS is blocked for this team. portal_new_conversation: type: boolean description: Whether learners may start conversations from the portal. created_at: type: integer description: Unix timestamp. updated_at: type: integer description: Unix timestamp. required: - name - label responses: Forbidden: description: >- The token is missing or invalid, or the service account behind it lacks the permission this endpoint requires. content: application/json: example: status: failed message: Lacking necessary permission add_contacts data: permission: add_contacts securitySchemes: conveyourToken: type: apiKey in: header name: x-conveyour-token description: >- Your API key token. Contacts endpoints require a **Server-only — Full API** key — see [Authentication](/quickstart). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.