Start Proposal Conversation

Opens the pre-hire direct-message thread for one of your proposals so you can talk to the candidate before hiring. Idempotent: if the thread already exists, you get the same conversationId back with created: false. Once you have the ID, send with POST /messages and read with GET /messages.

Proposal conversations are employer-first: only the job owner can open the thread, and the candidate cannot reply until the employer has sent the first message. This endpoint never creates any other kind of conversation — job threads come from hiring.

Requirements: messages:write scope + the public_api_messaging_writes feature + a claimed account (unclaimed accounts get 403 with details.reason: "account_claim_required" and a claimUrl). The proposal must be on a job you own.

Request

proposalIdstringpathrequired

The proposal whose thread to open.

No body.

Response

okboolean

true on success.

conversationIdstring

The conversation to use with the messages endpoints.

proposalIdstring

The proposal ID.

jobIdstring

The job the proposal belongs to.

createdboolean

true when a new thread was created, false when an existing one was returned.

Errors

Status	code	Meaning
400	BAD_REQUEST	Missing proposalId
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Missing messages:write scope, feature disabled, account not claimed (details.reason: "account_claim_required", details.claimUrl), the proposal is on another account’s job, or you are the candidate (details.reason: "employer_first_message_required" — only the employer opens the thread)
404	NOT_FOUND	No such proposal
409	CONFLICT	Proposal is not ready for messaging — details.reason: "proposal_not_ready_for_messaging" (e.g. missing invited user or linked job)

Request examples

curlCLIMCP: opentrain_start_proposal_conversation

curl

curl -sS -X POST https://app.opentrain.ai/api/public/v1/proposals/<PROPOSAL_ID>/conversation \
  -H "Authorization: Bearer $OT_API_TOKEN"

CLI

opentrain messages start-proposal-thread --proposal-id <PROPOSAL_ID> --json

MCP: opentrain_start_proposal_conversation

{
  "proposalId": "<PROPOSAL_ID>"
}

Response examples

200

{
  "ok": true,
  "conversationId": "<CONVERSATION_ID>",
  "proposalId": "<PROPOSAL_ID>",
  "jobId": "<JOB_ID>",
  "created": true
}