POST /v1/contacts
Create a contact
Create a contact
Creates a contact with source "api". Supports Idempotency-Key. Requires scope write:deals.
- Authentication: header
Authorization: Bearer rv_live_...(API keys and scopes) - Required scope:
write:deals
openapi.json).Parameters
| Field | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key | header | string | no | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response (Idempotent-Replay: true). |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
type | "lead" | "client" | "partner" | no | |
fullName | string | yes | |
phones | string[] | no | |
emails | string[] | no | |
telegramId | string | number | null | no | |
telegramUsername | string | null | no | |
viberId | string | null | no | |
ownerUserId | string | null (uuid) | no | |
tags | string[] | no | |
consentMarketing | boolean | no | |
preferredChannel | "telegram" | "viber" | "email" | "sms" | "webhook" | "in_app" | null | no | |
locale | "uk" | "pl" | "en" | no | |
notes | string | null | no | |
utm | object | null | no | |
allowDuplicate | boolean | no | Create even if a contact with the same phone/email/Telegram exists (otherwise 409 with duplicate_ids). |
Responses
201
The created contact.
application/json · Schema: Contact
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | |
type | "lead" | "client" | "partner" | yes | |
fullName | string | yes | |
phones | string[] | yes | E.164. |
emails | string[] | yes | |
telegramId | string | null | yes | |
telegramUsername | string | null | yes | |
viberId | string | null | yes | |
source | "site" | "telegram" | "instagram" | "referral" | "ads" | "manual" | "viber" | "widget" | "extension" | "api" | "import" | "marketplace" | yes | |
ownerUserId | string | null (uuid) | yes | |
tags | string[] | yes | |
consentMarketing | boolean | yes | |
preferredChannel | "telegram" | "viber" | "email" | "sms" | "webhook" | "in_app" | null | yes | |
locale | "uk" | "pl" | "en" | yes | |
notes | string | null | yes | |
createdAt | string | yes | ISO 8601 date-time (UTC). |
updatedAt | string | yes | ISO 8601 date-time (UTC). |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Schema: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Schema: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Schema: Problem
409
Conflict: duplicate contact (duplicate_ids), a request with this Idempotency-Key is still being processed, or the stage transition is blocked (missing[]).
application/problem+json · Schema: Problem
422
Well-formed but not acceptable data (unprocessable_input), or Idempotency-Key reused with a different request.
application/problem+json · Schema: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Schema: Problem