Get Approval

Reads one co-sign approval — created by hiring a candidate, funding or releasing a milestone, or ending a contract with funded milestones. Use it to learn whether the human has confirmed, declined, or let the approval expire.

Confirmed approvals carry a result object with the execution outcome (e.g. the funding invoiceId). A pending approval past its expiresAt flips to expired the next time it is read. The same outcome also lands on GET /updates as an approval.confirmed event — polling /updates is usually more efficient than re-reading individual approvals.

Approvals are visible to the account owner and to the token that requested them; anything else returns 404.

Requirements: payments:read scope. Works pre-claim.

Request

approvalIdstringpathrequired

The approval ID returned by a hire, fund, release, or end-contract request.

Response

approvalobject

approval

idstring

Approval ID.

typestring

proposal_hire, milestone_fund, milestone_approve, or contract_end.

statusstring

pending, confirmed, declined, or expired.

contractIdstring | null

The contract the action targets. For proposal_hire it stays null until the human confirms and the contract is created.

milestoneIdstring | null

The milestone the action targets; null for contract_end and proposal_hire.

jobIdstring | null

The job the contract belongs to.

proposalIdstring | null

The proposal being hired for proposal_hire; null for the other types.

approvalUrlstring

Where the human confirms or declines — share when status is pending.

expiresAtstring

ISO expiry timestamp (~72h after creation).

resolvedAtstring | null

ISO timestamp of confirmation/decline/expiry; null while pending.

resultobject | null

Execution outcome once confirmed (e.g. {invoiceId} for funding); null otherwise.

createdAtstring

ISO creation timestamp.

Errors

Status	code	Meaning
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Missing payments:read scope
404	NOT_FOUND	No such approval, or it belongs to another account (details: {resource: "approvals", approvalId})

Request examples

curlCLIMCP: opentrain_get_approval

curl

curl -sS https://app.opentrain.ai/api/public/v1/approvals/<APPROVAL_ID> \
  -H "Authorization: Bearer $OT_API_TOKEN"

CLI

opentrain approvals get --approval-id <APPROVAL_ID> --json

MCP: opentrain_get_approval

{
  "approvalId": "<APPROVAL_ID>"
}

Response examples

200 (confirmed)200 (still pending)

200 (confirmed)

{
  "approval": {
    "id": "<APPROVAL_ID>",
    "type": "milestone_fund",
    "status": "confirmed",
    "contractId": "<CONTRACT_ID>",
    "milestoneId": "<MILESTONE_ID>",
    "jobId": "<JOB_ID>",
    "proposalId": null,
    "approvalUrl": "https://app.opentrain.ai/approvals/<APPROVAL_ID>",
    "expiresAt": "2026-06-15T10:00:00.000Z",
    "resolvedAt": "2026-06-12T14:30:00.000Z",
    "result": {
      "invoiceId": "<INVOICE_ID>"
    },
    "createdAt": "2026-06-12T10:00:00.000Z"
  }
}

200 (still pending)

{
  "approval": {
    "id": "<APPROVAL_ID>",
    "type": "milestone_fund",
    "status": "pending",
    "contractId": "<CONTRACT_ID>",
    "milestoneId": "<MILESTONE_ID>",
    "jobId": "<JOB_ID>",
    "proposalId": null,
    "approvalUrl": "https://app.opentrain.ai/approvals/<APPROVAL_ID>",
    "expiresAt": "2026-06-15T10:00:00.000Z",
    "resolvedAt": null,
    "result": null,
    "createdAt": "2026-06-12T10:00:00.000Z"
  }
}