---
title: "Add a Circle member"
method: POST
path: "/api/v1/circles/{id}/members"
tags: ["Circles"]
---

# Add a Circle member

`POST /api/v1/circles/{id}/members`

## Request

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

Add a pending member by name (+ an optional pre-declared WhatsApp phone). Opts the Circle into Proof of Me.

## Path parameters

- `id` string, required: MongoDB ObjectId

## Request body

- CreateCircleMemberBody: Request body for adding a member to a Circle
  - `name` string, required
  - `whatsapp_phone` string: Optional pre-declared WhatsApp phone in E.164 (leading +); Telegram is captured at enrollment

## Response `201`

Member added

- CircleMember: A Circle member (channel presence and a masked enrollment phone only, never an identifier)
  - `id` string, required: MongoDB ObjectId
  - `name` string, required
  - `status` 'pending' | 'active', required
  - `has_telegram` boolean, required: Whether the member has a Telegram channel (declared or verified)
  - `has_whatsapp` boolean, required: Whether the member has a WhatsApp channel (declared or verified)
  - `mesh_opted_in` boolean, required
  - `mesh_opt_out` boolean, required: The member sent /opt_out: they receive no drills, reminders or checks they did not start themselves
  - `enrolled_phone_hint` string, nullable, required: Masked form of the phone the contact proved when they enrolled (the Telegram shared contact or the WhatsApp sender) — country prefix and last four digits only, never the full number. Lets the owner see who actually joined. Null until the member enrolls, and for members enrolled before it was recorded.
  - `enrolled_at` string, date-time, nullable, required
  - `last_verified_at` string, date-time, nullable, required: When this member last CONFIRMED an identity check asked of them — i.e. last proved it was them. Null until they have.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `404`: Circle not found

---

[API](https://skmtc.dev/proof/apis/proof-holdings-api.md) · [All operations](https://skmtc.dev/proof/apis/proof-holdings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proof/apis/proof-holdings-api/revisions/6b8d61ee354f?raw)