Skip to content
CRM Solid Docs
Open app

Create a contact

POST
/v1/contacts

Creates a new contact for the authenticated user. At least one of name, username, or phone must be provided. Defaults platform to telegram if omitted. Requires scope contacts:write.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

At least one of name, username, or phone is required.

object
platform

Platform for the new contact. Defaults to telegram.

string
default: telegram
Allowed values: telegram twitter
name
string
nullable
username

Handle with or without a leading @ - the @ is stripped server-side.

string
nullable
phone
string
nullable
notes
string
nullable
Example
{
  "platform": "telegram",
  "name": "Acme Inc.",
  "username": "john_doe",
  "phone": null,
  "notes": "Met at conference"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Contact created successfully.

A CRM contact record.

object
id
integer
platform

Social platform the contact belongs to.

string
Allowed values: telegram twitter
name
string
nullable
username

Handle without the leading @.

string
nullable
phone
string
nullable
email
string
nullable
company
string
nullable
notes
string
nullable
stage

CRM pipeline stage.

string
leadScore

Lead score 0-100 (higher = hotter). Null when not scored.

integer
nullable
leadScoreIsAi

True when the score was last set by AI, false for a manual override.

boolean
assignedToUserId

Team member the contact is assigned to.

integer
nullable
createdAt
string format: date-time
lastMessageAt
string format: date-time
nullable
hasUnreadMessages
boolean
tags

Attached tags (populated on GET by id, omitted in list responses).

Array<object>
nullable
object
id
integer
name
string
color

Hex color

string

400

Section titled “400 ”

The request body or parameters failed validation.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "bad_request",
  "message": "at least one of name, username, phone is required"
}

401

Section titled “401 ”

Missing or invalid bearer token.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "unauthorized",
  "message": "Invalid bearer principal"
}

403

Section titled “403 ”

The API key does not have the required scope for this operation.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "forbidden",
  "message": "scope contacts:write is required"
}

429

Section titled “429 ”

Per-key rate limit exceeded. Retry after the time indicated by X-RateLimit-Reset.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "rate_limited",
  "message": "rate limit exceeded"
}

Headers

Section titled “Headers ”
X-RateLimit-Limit
integer

Maximum requests allowed per minute for this key.

X-RateLimit-Remaining
integer

Requests remaining in the current window.

X-RateLimit-Reset
integer

Unix timestamp (seconds) when the rate limit window resets.