Group

post

https://api.marketcircle.net/v1/groups

Create a group

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

See Group for the attributes. name is required.

{
  "name": "Spring Campaign",
  "start": "2025-04-01T00:00:00Z",
  "end": "2025-05-31T00:00:00Z",
  "contacts": [{ "contact": "/v1/contacts/1000" }],
  "parent_group": "/v1/groups/6000"
}

A successful request returns 201 Created with the new group's reference, e.g. {"location": "/v1/groups/6005"}. If validation fails, the response is 400 with the errors for each attribute, e.g. {"start": [{"error": "blank"}]} when end is set without start.

Body Params

name

string

required

Name (max 512 characters). Required.

details

string

Details (max 2048 characters).

priority

integer

0 to 10

Priority from 0 (none) to 10.

category

string

Category name. Created if it does not exist. Send null or "" to clear.

keywords

array of strings

List of keyword names (max 64). Keywords that do not exist are created. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

keywords

extra_fields

object

Extra (custom) field values of the group, keyed by the field's default identifier even if it has been renamed. Each value is an object with a value key. Fields you leave out are not changed; send null or {} to clear all of them.

start

date-time

Start date, e.g. 2025-04-01T00:00:00Z. Required if end is set.

end

date-time

End date. Must be after start.

subgroups

array of strings

References of groups to make subgroups of this group, e.g. {"add": ["/v1/groups/2001"]} (max 32 subgroups, nested at most 5 levels deep). To detach a subgroup, set that group's parent_group to null.

subgroups

parent_group

string

Reference of the parent group, e.g. /v1/groups/1001. Send null to make this a top-level group.

appointments

array of objects

Appointments linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

appointments

contacts

array of objects

Contacts linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

contacts

companies

array of objects

Companies linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

companies

opportunities

array of objects

Opportunities linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

opportunities

projects

array of objects

Projects linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

projects

tasks

array of objects

Tasks linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

tasks

notes

array of objects

Notes linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

notes

forms

array of objects

Forms linked to the group. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

forms

email_messages

array of objects

Emails to link to the group. Write-only: use GET /v1/groups/{id}/emails to list them. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

email_messages

owner

string

Reference to the user responsible for the group, e.g. /v1/users/1000. Defaults to the user making the request.

Responses

201201 Created

400400 Bad Request