Propose an AWS referral update for a person to approve

PUT https://api.suger.cloud/org/{orgId}/cosell/referral/{referralId}/agentProposal

Stage a proposed change to an AWS co-sell referral, or record an outcome that needs a person, without changing the referral. The proposal is stored on the referral's metaInfo.partnerOps and shown to the seller on the referral page, where a person approves or rejects it. Use this in Review mode, or when an AWS rep is working the deal: send statusCode UPDATE_PROPOSED with the changed ACE opportunity fields in changes, shaped like the info.aceOpportunityV2 part of a merge=true UpdateCosellReferral body. When a fact needed for the change is missing, send NEEDS_NEXT_STEP, NEEDS_CONTACT, NEEDS_ADDRESS or NEEDS_OTHER with a reason and no changes; DUPLICATE_FOUND, BLOCKED_SENSITIVE and BLOCKED_PAYLOAD record those outcomes the same way. A new proposal replaces one already waiting. A proposed change must meet the rules an AI agent update meets: the referral is ACTIVE, IN_REVIEW, ACTION_REQUIRED or UPDATE_FAILED and stays open, no field that has a value is blanked, and the new text carries no other cloud's name, email address, phone number, pricing or discount term. A refused proposal returns 400 and stores nothing.

Parameters

Name	In	Type	Required	Description
`orgId`	path	string	yes	Organization ID
`referralId`	path	string	yes	Referral ID

Request Body

Required. Content-Type: application/json · Schema: ProposeCosellReferralUpdateRequest

ProposeCosellReferralUpdateRequest fields:

Field	Type	Required	Description
`changes`	object	no	Changes are the ACE opportunity fields to change (merge=true shape, under info.aceOpportunityV2). Required for UPDATE_PROPOSED, not allowed otherwise.
`predictedScore`	integer	no	PredictedScore is the predicted AWS quality score after the change, when checked.
`reason`	string	no	Reason is the specifics, shown next to the outcome. Required unless StatusCode is UPDATE_PROPOSED.
`skillId`	string	yes	SkillID is the skill that made the proposal.
`sources`	array<string>	no	Sources name where each fact came from.
`statusCode`	CosellAgentStatusCode	yes

Responses

200 — The referral's agent state after the proposal

Content-Type: application/json · Schema: CosellAgentReferralState

CosellAgentReferralState fields:

Field	Type	Required	Description
`approvedAt`	string	no
`approvedBy`	string	no	ApprovedBy and ApprovedAt record the person who approved the latest proposal.
`awsScoreBefore`	integer	no	AwsScoreBefore is AWS's quality score just before the agent's latest update, and AwsScoreBeforeAt when it was read, so the improvement can be shown.
`awsScoreBeforeAt`	string	no
`lastRejection`	CosellAgentRejection	no
`proposal`	CosellAgentProposal	no
`reason`	string	no	Reason is the specifics behind StatusCode, e.g. "No dated next step in any source".
`skillId`	string	no	SkillID is the skill that produced the latest outcome.
`statusCode`	CosellAgentStatusCode	no
`updatedAt`	string	no	UpdatedAt is when this state last changed.

CosellAgentRejection fields:

Field	Type	Required
`at`	string	yes
`by`	string	no
`reason`	string	no

CosellAgentProposal fields:

Field	Type	Required	Description
`changes`	object	yes	Changes are the ACE opportunity fields to change, shaped like the info.aceOpportunityV2 part of a merge=true update body.
`predictedScore`	integer	no	PredictedScore is the predicted AWS quality score after the change, when checked.
`proposedAt`	string	yes
`sources`	array<string>	no	Sources name where each fact came from (e.g. "Gong call on Sep 19").

400 — Bad request error

Content-Type: application/json · Schema: ErrorResponse

ErrorResponse fields:

Field	Type	Required
`code`	ErrorCode	no
`info`	object	no
`message`	string	no

404 — Referral not found

Content-Type: application/json · Schema: ErrorResponse

ErrorResponse fields:

Field	Type	Required
`code`	ErrorCode	no
`info`	object	no
`message`	string	no

500 — Internal server error

Content-Type: application/json · Schema: ErrorResponse

ErrorResponse fields:

Field	Type	Required
`code`	ErrorCode	no
`info`	object	no
`message`	string	no

Example

Generated from this operation's schema. Values are placeholders — substitute your own ids, and set SUGER_TOKEN to a bearer token from the OAuth client-credentials exchange.

Request

curl -X PUT 'https://api.suger.cloud/org/{orgId}/cosell/referral/{referralId}/agentProposal' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "skillId": "01H0000000000000000000",
  "statusCode": "UPDATE_PROPOSED"
}'

Response — 200

{
  "approvedAt": "2026-01-31T12:00:00Z",
  "approvedBy": "string",
  "awsScoreBefore": 1,
  "awsScoreBeforeAt": "2026-01-31T12:00:00Z",
  "lastRejection": {
    "at": "2026-01-31T12:00:00Z",
    "by": "string",
    "reason": "string"
  },
  "proposal": {
    "changes": {},
    "proposedAt": "2026-01-31T12:00:00Z",
    "predictedScore": 1,
    "sources": [
      "string"
    ]
  },
  "reason": "string",
  "skillId": "01H0000000000000000000",
  "statusCode": "UPDATE_PROPOSED",
  "updatedAt": "2026-01-31T12:00:00Z"
}

Error — 400

{
  "code": "InternalServerError",
  "message": "string"
}

View as Markdown · API reference overview

Spotted something wrong or out of date on this page? Tell us and we'll correct it.