POST /v1/actions/get-contact

Fetches a single contact. Lookup by exactly one of contact_id, phone, or email.

POST /api/v1/actions/get-contact

Request body

Field	Type	Required	Notes
contact_id	UUID	one of	Internal id
phone	string	one of	International format with +
email	string	one of	Must be a valid email

curl -X POST https://www.qyvo.io/api/v1/actions/get-contact \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+14155550123"}'

const contact = await fetch('https://www.qyvo.io/api/v1/actions/get-contact', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.QYVO_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ phone: '+14155550123' }),
}).then((r) => r.json());

$contact = Http::withToken(env('QYVO_TOKEN'))
    ->post('https://www.qyvo.io/api/v1/actions/get-contact', [
        'phone' => '+14155550123',
    ])
    ->json();

import os, httpx
contact = httpx.post(
    'https://www.qyvo.io/api/v1/actions/get-contact',
    headers={'Authorization': f"Bearer {os.environ['QYVO_TOKEN']}"},
    json={'phone': '+14155550123'},
).json()

Response — 200 OK

{
  "id": "01J1Y...",
  "phone": "+14155550123",
  "name": "Romain",
  "email": "[email protected]",
  "source": "shopify",
  "locale": "fr",
  "metadata": { "shopify_id": "12345" },
  "tags": ["vip", "fr-FR"],
  "opted_in_at": "2026-04-15T10:32:00+00:00",
  "opted_out_at": null,
  "last_message_at": "2026-05-07T08:14:23+00:00",
  "total_messages": 27,
  "created_at": "2026-04-15T10:32:00+00:00"
}

Field	Notes
source	Where the contact entered Qyvo: manual, csv_import, shopify, woocommerce, widget, zapier, api
opted_in_at / opted_out_at	Consent state — used to gate marketing sends
last_message_at	Most recent message in either direction. Used to compute the 24h customer service window.
total_messages	Lifetime count

Errors

Status	Cause
404	Contact not found
422	None of contact_id, phone, email provided