Skip to main content
POST
Create a contact

Authorizations

Authorization
string
header
required

Organization-scoped bearer credential: a customer API key (1club_sk_live_...) or an MCP OAuth access token.

Headers

Idempotency-Key
string

Retry-safe key; a repeat of the same request replays the first response

Maximum string length: 255

Body

application/json

Fields accepted when creating a contact. At least one of email or phone is required so the person stays reachable and findable.

firstName
string
required

Given name. The display name is always recomputed from first + last.

Maximum string length: 255
lastName
string
Maximum string length: 255
email
string<email>

Unique within the organization. Cannot be changed for a contact whose email is also their 1club login.

Maximum string length: 255
phone
string

Canonicalized to E.164 when the organization is configured for it.

Maximum string length: 50
pipelineStageId
integer

Put the new contact in this sales pipeline stage (GET /v1/platform/pipeline-stages), which makes them a lead.

pipelineLostReason
enum<string>

Why the lead was lost. Only with a pipelineStageId naming the Lost stage (kind cold); sent with any other stage it is refused. Optional: a move to Lost without it reads as unknown. On a contact already in Lost it replaces the recorded reason.

Available options:
price,
timing,
chose_competitor,
location,
no_response,
not_interested,
not_a_fit,
other
pipelineLostNote
string

What the reason leaves out. Required when pipelineLostReason is other.

Maximum string length: 500
sourceId
integer

Where the contact came from (GET /v1/platform/contact-sources).

assignedToId
integer

The staff member (organization user id) following the contact up.

Response

Contact created

A contact (customer) in the organization. Reference the id as contactId when creating a booking.

id
integer
uuid
string<uuid>

Stable unguessable identifier. Prefer this over id when storing a reference.

name
string
firstName
string
lastName
string | null
email
string | null
phone
string | null
type
string | null

Derived contact type (e.g. contact, member, lead). archived marks a retired contact — hidden from the list and from search, but still readable by id.

pipelineStageId
integer | null

The sales pipeline stage the contact is in, or null when they are not in the pipeline.

pipelineLostReason
enum<string> | null

Why the lead was lost, while they are in the Lost stage. Null outside it, or when no reason was given.

Available options:
price,
timing,
chose_competitor,
location,
no_response,
not_interested,
not_a_fit,
other
pipelineLostNote
string | null

The note given with the lost reason.

sourceId
integer | null

Where the contact came from.

assignedToId
integer | null

The staff member (organization user id) following the contact up.

createdAt
string<date-time>