API reference / People writes

Start a conversation

Written and maintained by The ProspectAPIs team

POST/v1/chats

POST /v1/chats is the ProspectAPIs operation startChat, in the People writes group of the REST API. Start a new conversation from your connected account with one person, or a group of up to 50 (subject is the group's title and needs two or more people), with an optional attachment. $0.03 per action, the price of a message. Answers thread_id for GET /v1/messages/thread (null when it could not be read back; the thread then shows in GET /v1/messages). Acts on your own connected account (connect one first with POST /v1/accounts/session). Billed per call once the write product is live; while it is not yet on sale the call is free (GET /pricing reports people_writes.available). Until this action is switched on it answers 503 temporarily_unavailable and nothing is charged (GET /pricing lists it in people_writes.routes but not in available_routes). Cost: Not available yet. Send your API key as a Bearer token in the Authorization header.

The quickstart shows this call in context, next to the first requests most integrations make.

Parameters

Request body

JSON.

{
  "person_refs": [
    "person refs"
  ],
  "text": "text"
}

Responses

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

200 response fields

Done. Our neutral confirmation. The body is a PeopleWriteResult.

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl -X POST https://api.prospectapis.com/v1/chats \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "person_refs": [ "person refs" ], "text": "text" }'

const res = await fetch("https://api.prospectapis.com/v1/chats", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "person_refs": [
      "person refs"
    ],
    "text": "text"
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

import os, requests

res = requests.post(
    "https://api.prospectapis.com/v1/chats",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    json={
        "person_refs": ["person refs"],
        "text": "text",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

Billing reserves before it serves: the call holds what it may cost, serves at most what that hold covers, and refunds the rest when the response closes. Any non-2xx answer refunds the whole hold, so a failed call costs nothing. The response reports your balance in X-Credits-Remaining.

Related

Previous operation: Mark a thread read. Next operation: Read a conversation thread (live). Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values (this call acts for real, so use real inputs).