Create group
Creates a new group in a team.
HTTP method and URL path
https://api.canva.com /admin /v1 /teams/{teamId}/groupsAuthentication and authorization
This endpoint requires a valid access token that was generated using client credentials.
Scopes
The access token must have all the following scopes (permissions):
admin:group:write
Header parameters
Content-TypestringIndicates the media type of the information sent in the request. This must be set to application/json.
For example: Content-Type: application/json
Path parameters
teamIdstringThe team ID the group belongs to.
Body parameters
namestringThe display name for the group.
Minimum length: 1
Maximum length: 255
descriptionstringThe description for the group.
Maximum length: 255
Example request
Examples for using the /v1/teams/{teamId}/groups endpoint:
curl --request POST 'https://api.canva.com/admin/v1/teams/{teamId}/groups' \--header 'Authorization: Bearer {token}' \--header 'Content-Type: application/json' \--data '{"name": "ACME Marketing Group","description": "All staff members in the marketing department."}'
const fetch = require("node-fetch");fetch("https://api.canva.com/admin/v1/teams/{teamId}/groups", {method: "POST",headers: {"Authorization": "Bearer {token}","Content-Type": "application/json",},body: JSON.stringify({"name": "ACME Marketing Group","description": "All staff members in the marketing department."}),}).then(async (response) => {const data = await response.json();console.log(data);}).catch(err => console.error(err));
import java.io.IOException;import java.net.URI;import java.net.http.*;public class ApiExample {public static void main(String[] args) throws IOException, InterruptedException {HttpRequest request = HttpRequest.newBuilder().uri(URI.create("https://api.canva.com/admin/v1/teams/{teamId}/groups")).header("Authorization", "Bearer {token}").header("Content-Type", "application/json").method("POST", HttpRequest.BodyPublishers.ofString("{\"name\": \"ACME Marketing Group\", \"description\": \"All staff members in the marketing department.\"}")).build();HttpResponse<String> response = HttpClient.newHttpClient().send(request,HttpResponse.BodyHandlers.ofString());System.out.println(response.body());}}
import requestsheaders = {"Authorization": "Bearer {token}","Content-Type": "application/json"}data = {"name": "ACME Marketing Group","description": "All staff members in the marketing department."}response = requests.post("https://api.canva.com/admin/v1/teams/{teamId}/groups",headers=headers,json=data)print(response.json())
using System.Net.Http;var client = new HttpClient();var request = new HttpRequestMessage{Method = HttpMethod.Post,RequestUri = new Uri("https://api.canva.com/admin/v1/teams/{teamId}/groups"),Headers ={{ "Authorization", "Bearer {token}" },},Content = new StringContent("{\"name\": \"ACME Marketing Group\", \"description\": \"All staff members in the marketing department.\"}",Encoding.UTF8,"application/json"),};using (var response = await client.SendAsync(request)){response.EnsureSuccessStatusCode();var body = await response.Content.ReadAsStringAsync();Console.WriteLine(body);};
package mainimport ("fmt""io""net/http""strings")func main() {payload := strings.NewReader(`{"name": "ACME Marketing Group","description": "All staff members in the marketing department."}`)url := "https://api.canva.com/admin/v1/teams/{teamId}/groups"req, _ := http.NewRequest("POST", url, payload)req.Header.Add("Authorization", "Bearer {token}")req.Header.Add("Content-Type", "application/json")res, _ := http.DefaultClient.Do(req)defer res.Body.Close()body, _ := io.ReadAll(res.Body)fmt.Println(string(body))}
$curl = curl_init();curl_setopt_array($curl, array(CURLOPT_URL => "https://api.canva.com/admin/v1/teams/{teamId}/groups",CURLOPT_CUSTOMREQUEST => "POST",CURLOPT_RETURNTRANSFER => true,CURLOPT_HTTPHEADER => array('Authorization: Bearer {token}','Content-Type: application/json',),CURLOPT_POSTFIELDS => json_encode(["name" => "ACME Marketing Group","description" => "All staff members in the marketing department."])));$response = curl_exec($curl);$err = curl_error($curl);curl_close($curl);if (empty($err)) {echo $response;} else {echo "Error: " . $err;}
require 'net/http'require 'uri'url = URI('https://api.canva.com/admin/v1/teams/{teamId}/groups')http = Net::HTTP.new(url.host, url.port)http.use_ssl = truerequest = Net::HTTP::Post.new(url)request['Authorization'] = 'Bearer {token}'request['Content-Type'] = 'application/json'request.body = <<REQUEST_BODY{"name": "ACME Marketing Group","description": "All staff members in the marketing department."}REQUEST_BODYresponse = http.request(request)puts response.read_body
Success response
If successful, the endpoint returns a 200 response with a JSON body with the following parameters:
groupGroupA group.
idstringThe group ID. This ID is generated by Canva and is unique within the team.
namestringThe name of the group.
created_atintegerWhen the group was created, as a Unix timestamp (in seconds since the Unix Epoch).
updated_atintegerWhen the group was last updated, as a Unix timestamp (in seconds since the Unix Epoch).
descriptionstringThe description of the group.
Example response
{"group": {"id": "GAAAAAAAAA1","name": "ACME Marketing Group","description": "All staff members in the marketing department.","created_at": 1601404800,"updated_at": 1601404900}}
Error responses
400 Bad Request
codestringA short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see Error responses.
messagestringA human-readable description of what went wrong.
Example error responses
A group with the same name already exists
{"code": "display_name_unavailable","message": "A group with the same name already exists in the team."}
The input is unsafe
{"code": "input_unsafe","message": "Input is unsafe"}
404 Not Found
codestringA short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see Error responses.
messagestringA human-readable description of what went wrong.
Example error response
The team was not found
{"code": "team_not_found","message": "Team {teamId} not found"}