Create contact

/contactsPOST

Adds a new contact profile to your account's default API contact list, including custom attributes.

Authorization

BearerAuth *Bearer <token>

API key generated under Account Settings → API Keys (rk_live_...). Send as header Authorization: Bearer <key>.

Request Bodyapplication/jsonrequired

phone_number?string

Phone number in E.164 format.

Example: "+2348012345678"

first_name?string

Example: "Ada"

last_name?string

Example: "Obi"

email?string (email)

Example: "[email protected]"

external_customer_id?string

Example: "cus_92841"

company?string

Example: "Ada Foods"

tags?string[]

opted_out?boolean

Default: falseExample: false

whatsapp_opt_in?boolean

Whether the contact has explicitly consented to WhatsApp messages.

Default: false

whatsapp_opt_in_source?string

Audit label describing where WhatsApp consent was collected.

Example: "tailora_checkout"

custom_fields?object

Response

201 · Contact created successfully

id?integer

Example: 1042

phone_number?string

Example: "+2348012345678"

status?string

Example: "created"

401 · Unauthorized

success *boolean

Example: false

error *string

Human-readable error message explaining the failure reason.

Example: "Recipient not reachable on WhatsApp."

error_code *string

Stable machine-readable error code.

Example: "recipient_not_on_whatsapp"

422 · Validation error

errors *string[]

Request example

curl -X POST "https://convert.ruut.chat/api/v1/contacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+2348012345678",
  "first_name": "Ada",
  "last_name": "Obi",
  "email": "[email protected]",
  "custom_fields": {
    "account_tier": "gold",
    "vip_status": true
  }
}'

Response example

{
  "id": 1042,
  "phone_number": "+2348012345678",
  "status": "created"
}