Skip to main content
POST
/
api
/
public
/
v1
/
proposals
/
{proposalId}
/
conversation
curl -sS -X POST https://app.opentrain.ai/api/public/v1/proposals/<PROPOSAL_ID>/conversation \
  -H "Authorization: Bearer $OT_API_TOKEN"

{
  "ok": true,
  "conversationId": "<CONVERSATION_ID>",
  "proposalId": "<PROPOSAL_ID>",
  "jobId": "<JOB_ID>",
  "created": true
}
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

​
proposalId
string
required
The proposal whose thread to open.
No body.

​
Response

​
ok
boolean
true on success.
​
conversationId
string
The conversation to use with the messages endpoints.
​
proposalId
string
The proposal ID.
​
jobId
string
The job the proposal belongs to.
​
created
boolean
true when a new thread was created, false when an existing one was returned.

​
Errors

StatuscodeMeaning
400BAD_REQUESTMissing proposalId
401UNAUTHORIZEDMissing or invalid token
403FORBIDDENMissing 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)
404NOT_FOUNDNo such proposal
409CONFLICTProposal is not ready for messaging — details.reason: "proposal_not_ready_for_messaging" (e.g. missing invited user or linked job)
curl -sS -X POST https://app.opentrain.ai/api/public/v1/proposals/<PROPOSAL_ID>/conversation \
  -H "Authorization: Bearer $OT_API_TOKEN"

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