Create a circle | PlannrCRM API documentation

Create a circle Run in API Explorer

POST /api/v1/circles

Personal access token & O auth2

Headers

X-PLANNR-ACCOUNT-UUID string

application/json

Body

name string Required

Circle name
bg_colour string

Hex colour for avatar background
account_uuids array[string(uuid)] Required

Account UUIDs that are being added to the circle. Between 1 and 100 account UUIDs are required.
group_uuids array[string(uuid)] Required

Groups UUIDs the circle will belong to. Can belong to a maximum of 50 groups.

Responses

201 application/json
Hide response attributes Show response attributes object
- uuid string
  
  The UUID of the resource.
- created_at string
  
  The timestamp of when the resource was created.
- updated_at string
  
  The timestamp of when the resource was updated.
- name string
  
  The Circle name
- photo_url string
  
  URL for initial avatar image
- bg_colour string
  
  Hex colour background for avatar
- accounts array[object]
  
  Accounts belonging to the circle
  
  Hide accounts attributes Show accounts attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  type string
  
  role string
  
  first_name string
  
  last_name string
  
  name string
  
  email string
  
  photo_url string
  
  firm string
  
  primary_phone_number string
  
  primary_email string
  
  current_time_entry string
  
  assigned_adviser string
  
  assigned_administrator string
  
  assigned_paraplanner string
  
  introduced_by string
  
  business_unit string
  
  groups string
  
  tags string
  
  owners string
  
  first_contact_date string
  
  next_review_date string
  
  previous_review_date string
  
  anniversary_review_date string
  
  with_login boolean
  
  has_joint_account boolean
  
  can_be_deleted string
  
  joint_account_circle string
  
  circles string
  
  ownership_percentage integer
  
  inactive_at string
  
  last_interaction_at string
  
  referral_code string
  
  permissions object
  
  Hide permissions attributes Show permissions attributes object
  
  firm:read array[string]
  
  network:read array[string]
  
  custom_fields string
  
  external_references string
- groups array[object]
  
  Groups the circle belongs to
  
  Hide groups attributes Show groups attributes object
  
  uuid string
  
  name string
  
  slug string
  
  participants_count string
  
  participants object
  
  Hide participants attributes Show participants attributes object
  
  uuid object
  
  Hide uuid attributes Show uuid attributes object
  
  example string
  
  description string
  
  role object
  
  Hide role attributes Show role attributes object
  
  example string
  
  description string
  
  first_name object
  
  Hide first_name attributes Show first_name attributes object
  
  example string
  
  description string
  
  last_name object
  
  Hide last_name attributes Show last_name attributes object
  
  example string
  
  description string
  
  name object
  
  Hide name attributes Show name attributes object
  
  example string
  
  description string
  
  email object
  
  Hide email attributes Show email attributes object
  
  example string
  
  description string
  
  created_at string
  
  updated_at string
- joint_account_uuid string
  
  uuid of joint account where circle created from joint account
- login_access_level string
  
  The access level in context of an account. Note this field is only returned when using the accounts API. Available values: read and write
- external_references array[object]
  
  The external references that have been added to the client.
  
  Hide external_references attributes Show external_references attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  third_party string
  
  reference string

POST /api/v1/circles

curl \
 --request POST 'https://api.plannrcrm.com/api/v1/circles' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"name":"Jones Family","bg_colour":"#DDDDDD","account_uuids":["aead28d1-b050-4205-8597-4d7a3b5b2626","82058461-7dea-4f84-8917-646cc4a8970d","919c98f5-0a4c-4b12-a13e-3ca86db59f23"],"group_uuids":["0a7fb15b-fb2b-4a1b-b242-82855d00a89f","305c9dc1-489f-4ed5-969c-a9e9f9e5d404","2964e494-79ec-4a3d-860b-1235397e4a44"]}'

Request examples

# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "name": "Jones Family",
  "bg_colour": "#DDDDDD",
  "account_uuids": [
    "aead28d1-b050-4205-8597-4d7a3b5b2626",
    "82058461-7dea-4f84-8917-646cc4a8970d",
    "919c98f5-0a4c-4b12-a13e-3ca86db59f23"
  ],
  "group_uuids": [
    "0a7fb15b-fb2b-4a1b-b242-82855d00a89f",
    "305c9dc1-489f-4ed5-969c-a9e9f9e5d404",
    "2964e494-79ec-4a3d-860b-1235397e4a44"
  ]
}

Response examples (201)

{
  "uuid": "e74ce589-8199-4170-bfba-7e3bf4c00437",
  "created_at": "2026-04-29T12:52:59+01:00",
  "updated_at": "2026-04-29T12:52:59+01:00",
  "name": "Jones Family",
  "photo_url": "https://eu.ui-avatars.com/api/?name=jones+family",
  "bg_colour": "#35f4e1",
  "accounts": [
    {
      "uuid": "6cbb68d4-a64b-4201-9bd7-6e99546850c7",
      "created_at": "2026-04-29T12:52:59+01:00",
      "updated_at": "2026-04-29T12:52:59+01:00",
      "type": "client",
      "role": "client",
      "first_name": "Gareth",
      "last_name": "Thompson",
      "name": "Gareth Thompson",
      "email": "gareth@codepotato.co.uk",
      "photo_url": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
      "firm": "App\\Http\\Resources\\FirmResource",
      "primary_phone_number": "App\\Http\\Resources\\ContactDetailResource",
      "primary_email": "App\\Http\\Resources\\ContactDetailResource",
      "current_time_entry": "App\\Http\\Resources\\TimeEntryResource",
      "assigned_adviser": "App\\Http\\Resources\\AccountResource",
      "assigned_administrator": "App\\Http\\Resources\\AccountResource",
      "assigned_paraplanner": "App\\Http\\Resources\\AccountResource",
      "introduced_by": "App\\Http\\Resources\\AccountResource",
      "business_unit": "App\\Http\\Resources\\BusinessUnitResource",
      "groups": "App\\Http\\Resources\\GroupResource",
      "tags": "App\\Http\\Resources\\TagResource",
      "owners": "App\\Http\\Resources\\AccountResource",
      "first_contact_date": "2026-04-29T12:52:59+01:00",
      "next_review_date": "2026-04-29T12:52:59+01:00",
      "previous_review_date": "2026-04-29T12:52:59+01:00",
      "anniversary_review_date": "2026-04-29T12:52:59+01:00",
      "with_login": true,
      "has_joint_account": true,
      "can_be_deleted": "false",
      "joint_account_circle": "App\\Http\\Resources\\CircleResource",
      "circles": "App\\Http\\Resources\\CircleResource",
      "ownership_percentage": 100,
      "inactive_at": "2026-04-29",
      "last_interaction_at": "2026-04-29 12:52:59",
      "referral_code": "ABC12345",
      "permissions": {
        "firm:read": [
          "firm"
        ],
        "network:read": [
          "network:uuid"
        ]
      },
      "custom_fields": "App\\Http\\Resources\\CustomFieldValueResource",
      "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
    }
  ],
  "groups": [
    {
      "uuid": "cd6c85e5-53f7-4e57-901d-2f68b33a5c3a",
      "name": "finance",
      "slug": "finance",
      "participants_count": "3",
      "participants": {
        "uuid": {
          "example": "ebb133be-6926-4fa9-80b4-ee6470d77e46",
          "description": "UUID of the account"
        },
        "role": {
          "example": "client",
          "description": "Role of the account"
        },
        "first_name": {
          "example": "Gareth",
          "description": "First name of the account"
        },
        "last_name": {
          "example": "Thompson",
          "description": "Last name of the account"
        },
        "name": {
          "example": "Gareth Thompson",
          "description": "Name of the account"
        },
        "email": {
          "example": "gareth@codepotato.co.uk",
          "description": "Email of the account"
        }
      },
      "created_at": "2026-04-29T12:52:59+01:00",
      "updated_at": "2026-04-29T12:52:59+01:00"
    }
  ],
  "joint_account_uuid": "3b96a05a-0187-4c3f-8680-81a1483e9c5e",
  "login_access_level": "write",
  "external_references": [
    {
      "uuid": "4e391934-7df6-4604-b07d-7816cd1b4cbe",
      "created_at": "2026-04-29T12:52:59+01:00",
      "updated_at": "2026-04-29T12:52:59+01:00",
      "third_party": "nucleus",
      "reference": "AB123456"
    }
  ]
}