Circles

Create a Circle

Create a named group of trusted contacts. Initial members may declare channels inline.

post/api/v1/circles

Request

Base URL: https://api.proof.holdings
URL: https://api.proof.holdings/api/v1/circles
Auth: one of:
- HTTP bearer
- API key in cookie auth_token

Request body

namestring required

owner_namestring nullable

How this Circle's members know its owner ("Dad", "Giorgi"). The bots name the owner by it; while it is empty they name nobody — the Circle's name labels the group, never the person. Trimmed; an empty value clears it.

profile_idstring

Optional public profile to bind for branded messages (create-only). The caller must own it (403 otherwise).

proof_me_enabledboolean

Opt this Circle into Proof of Me drills

Example request

{
  "name": "Family",
  "owner_name": "Dad",
  "profile_id": "507f1f77bcf86cd799439011",
  "members": [
    {
      "name": "Mum",
      "whatsapp_phone": "+15551112222"
    }
  ]
}

Response

Circle created

idstring required

MongoDB ObjectId

user_idstring required

MongoDB ObjectId

namestring nullable required

owner_namestring nullable required

How this Circle's members know its owner; null when unset

profile_idstring required

MongoDB ObjectId

environment'production' | 'test' required

proof_me_enabledboolean required

status'active' | 'archived' required

Lifecycle state of a Circle (archived = soft-retired)

member_countinteger required

created_atstring date-time required

updated_atstring date-time required

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "user_id": "507f1f77bcf86cd799439011",
  "name": "Family",
  "owner_name": "Dad",
  "profile_id": "507f1f77bcf86cd799439011",
  "environment": "production",
  "status": "active",
  "member_count": 2,
  "members": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Mum",
      "status": "active",
      "enrolled_phone_hint": "+9••••••4171"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.