Getting Started Guides

Four common use-cases to get you moving. Each example is available as a REST API call, a CLI command, and a TypeScript SDK snippet, so pick the interface that fits your context.

Before you start. Every example on this page needs two things: an API key, and a connected LinkedIn account whose acc_... id you substitute for acc_YOUR_ACCOUNT_ID. If you have not connected one yet, start with Quickstart. Read your ids with GET /v1/accounts (the one call on this page that needs no account) or curviate account list. Skip this and every call below returns 404 ACCOUNT_NOT_FOUND.

Almost every Curviate path is account-scoped: account_id is a path segment, right after /v1/. A call that omits it does not fall back to a default account, it misses the route entirely and returns 404 RESOURCE_NOT_FOUND, which looks like a bad chat or user id. If you see RESOURCE_NOT_FOUND, check the path shape before you check your ids.

For the full API surface, see the interactive API reference or the OpenAPI spec.

Send a message

Send a message into an existing chat thread. You need the chat_id of the thread; retrieve it from the inbox (GET /v1/{account_id}/chats or curviate inbox list).

curl -X POST https://api.curviate.com/v1/acc_YOUR_ACCOUNT_ID/chats/chat_YOUR_CHAT_ID/messages \
  -H "Authorization: Bearer cvt_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hi! Following up on your message."}'

curviate message chat_YOUR_CHAT_ID "Hi! Following up on your message." \
  --account acc_YOUR_ACCOUNT_ID

import { Curviate } from "@curviate/sdk";
 
const curviate = new Curviate({ apiKey: process.env.CURVIATE_API_KEY! });
 
const result = await curviate
  .account("acc_YOUR_ACCOUNT_ID")
  .messaging.sendMessage("chat_YOUR_CHAT_ID", {
    text: "Hi! Following up on your message.",
  });
 
console.log("Message sent:", result.message_id);

Get a person's profile

Retrieve a LinkedIn member's profile by public identifier, URL, or member ID. The userId is the slug after linkedin.com/in/, for example williamhgates (or the sentinel "me" for the connected account's own profile). account_id is a path segment, not a query param.

curl "https://api.curviate.com/v1/acc_YOUR_ACCOUNT_ID/users/williamhgates" \
  -H "Authorization: Bearer cvt_live_..."

curviate profile williamhgates --account acc_YOUR_ACCOUNT_ID

import { Curviate } from "@curviate/sdk";
 
const curviate = new Curviate({ apiKey: process.env.CURVIATE_API_KEY! });
 
const profile = await curviate
  .account("acc_YOUR_ACCOUNT_ID")
  .users.get("williamhgates");
 
console.log(`${profile.first_name} ${profile.last_name}: ${profile.description}`);

Key response fields: first_name, last_name, description (the profile headline; the field is not called headline), profile_url, public_identifier.

List new connections

After sending connection requests, call listRelations to see which requests were recently accepted. Each connection item includes a created_at timestamp (ISO-8601) indicating when the connection was established; filter by this field to find new accepts.

# List your 1st-degree connections, sorted by recency
curl "https://api.curviate.com/v1/acc_YOUR_ACCOUNT_ID/profiles/relations?limit=20" \
  -H "Authorization: Bearer cvt_live_..."

curviate profile connections --account acc_YOUR_ACCOUNT_ID --limit 20

import { Curviate } from "@curviate/sdk";
 
const curviate = new Curviate({ apiKey: process.env.CURVIATE_API_KEY! });
 
const page = await curviate
  .account("acc_YOUR_ACCOUNT_ID")
  .users.listRelations({ limit: 20 });
 
// Find connections established in the last 24 hours
const cutoff = new Date(Date.now() - 86_400_000).toISOString();
const newConnections = (page.items ?? []).filter(
  (c) => c.created_at >= cutoff
);
 
console.log(`New connections: ${newConnections.length}`);
for (const c of newConnections) {
  console.log(`  ${c.first_name} ${c.last_name}, connected at ${c.created_at}`);
}

Reply as a company page

If your account manages a company page (Beta), you can reply to a message that came in on the page, not just as yourself. Discover the page's inbox, read one of its chat ids, then send into that chat id with the same send-message call you already use. No separate parameter switches identity: the chat id alone decides it, and the response's sent_as field confirms which identity actually sent it. Company pages are reply-only. They can answer an existing conversation but cannot start a new one.

# 1. Discover the company inbox
curl "https://api.curviate.com/v1/acc_YOUR_ACCOUNT_ID/inboxes?kind=company" \
  -H "Authorization: Bearer cvt_live_..."
 
# 2. Read its conversations (use the inbox id from step 1, e.g. COMPANY_83734124_PRIMARY)
curl "https://api.curviate.com/v1/acc_YOUR_ACCOUNT_ID/inboxes/COMPANY_83734124_PRIMARY/chats" \
  -H "Authorization: Bearer cvt_live_..."
 
# 3. Reply with the existing send-message endpoint, using that chat id
curl -X POST https://api.curviate.com/v1/acc_YOUR_ACCOUNT_ID/chats/COMPANY_83734124_2-YTQ3ODU3Njgt/messages \
  -H "Authorization: Bearer cvt_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks for reaching out!"}'

# 1. Discover the company inbox
curviate inboxes list --kind company --account acc_YOUR_ACCOUNT_ID
 
# 2. Read its conversations (use the inbox id from step 1)
curviate inboxes chats COMPANY_83734124_PRIMARY --account acc_YOUR_ACCOUNT_ID
 
# 3. Reply with the existing message command, using that chat id
curviate message send COMPANY_83734124_2-YTQ3ODU3Njgt "Thanks for reaching out!" \
  --account acc_YOUR_ACCOUNT_ID

message send's default output prints Sent as <name> (company page) to stderr right after the send, so you can see which identity replied without inspecting raw JSON.

import { Curviate } from "@curviate/sdk";
 
const curviate = new Curviate({ apiKey: process.env.CURVIATE_API_KEY! });
const acc = curviate.account("acc_YOUR_ACCOUNT_ID");
 
// 1. Discover the company inbox
const { items: inboxes } = await acc.inboxes.list({ kind: "company" });
const pageInbox = inboxes[0]!; // e.g. id "COMPANY_83734124_PRIMARY", reply_only: true
 
// 2. Read its conversations
const { items: chats } = await acc.inboxes.listChats(pageInbox.id);
const chatId = chats[0]!.id as string; // e.g. "COMPANY_83734124_2-YTQ3ODU3Njgt"
 
// 3. Reply with the existing send-message call
const sent = await acc.messaging.sendMessage(chatId, { text: "Thanks for reaching out!" });
console.log(sent.sent_as); // { kind: "company", company_id: "112013061", name: "Acme Inc" }

The same chat id space works for personal conversations too: a CLASSIC_ chat id sends as the connected member and echoes sent_as: { kind: "personal" }. Never infer the acting identity from a message's sender field, only from sent_as.