API Reference

Create a member

post
https://api.community.com/members

Creates a member in the community associated with your API key. A member is uniquely identified by the combination of communication_channel and communication_channel_id.

On success, the response is a Member object, the same one returned by GET /members/{member_id}. A newly created member has no subcommunities and no activity.

When the member already exists

If a member with the same communication_channel and communication_channel_id already exists, the request returns 409 Conflict with one of these error codes:

  • member_already_exists: the member is new or live. On a retry, treat it as success and find the member with GET /members.
  • member_not_live: the member left, for example opted_out or blocked. The person must opt back in on their own.
  • member_deleted: the member was deleted. The person can join again on their own.

Retries and errors

All validation runs before anything is written, so any 4xx response means no member was created.

If you get a 500 or the request times out, send the same request again. If the retry returns member_already_exists, your original request succeeded.

Custom data

If you include custom_data and the response comes back with an empty custom_data object, the member was created but the custom data wasn’t saved. Resend it with PATCH /members/{member_id}.

WhatsApp members and phone numbers

When you create a WhatsApp member using a phone number, we check for an existing member with that number, including members whose WhatsApp address has since changed to a WhatsApp user ID. If a match is found, you’ll get a 409 as described above.

Body Params

The member to create.

Fields accepted when creating a member.

string
enum

How consent was captured. preopt requires the client to be explicitly allowed, and is refused
with activation_mode_not_permitted otherwise.

Allowed:
string | null

City.

string
enum
Defaults to sms

The channel that reaches the member. Half of the natural key, with communication_channel_id.
You cannot create amb members.

Allowed:
string
required
length ≤ 255

The member's address on its channel. For sms, the phone number in E.164 format. For whatsapp,
the phone number in E.164 format or the WhatsApp user id. A WhatsApp user id must belong to a
member the platform already knows.

string | null

Country name.

string | null

ISO country code.

custom_data
object

Values for your community's custom member fields.

Each key is key:source.

  • key is the field's key, such as favorite_color for a field named "Favorite Color". It is not the display name.
  • source is client for a field your community fills, or fan for a field the member fills on the sign-up form.

The keys a member already holds come back in custom_data on GET /members/{member_id}.

Every value is a string, whatever the field's type:

Field typeExample value
string"blue"
integer"42"
decimal"9.99", with at most 2 or 4 decimal places, as the field defines
boolean"true" or "false"
date"2026-10-21", as YYYY-MM-DD
datetime"2026-10-21T14:30:00Z", as ISO 8601 in UTC

A value holds at most 100 characters. A key that is not a field of your community is refused with
custom_field_not_found. A value that its field's type cannot hold is refused with invalid_value.

date

Date of birth. Checked against the community's age gate.

string | null

Email address.

string | null

Given name.

string | null

Gender, from the closed set configured on the sign-up form.

string | null

Family name.

string | null

Abbreviated state or province code.

string | null

Geographic state or province.

string | null

Postal code.

Headers
string

Pins the API version for this request as YYYY-MM-DD. Defaults to the version pinned to your
credential.

Responses

Callback

Updated 18 days ago

Did this page help you?
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 18 days ago

Did this page help you?