# Predict AWS Opportunity Quality Score

`POST https://api.suger.cloud/org/{orgId}/cosell/referral/predict-quality-score`

Predict the AWS opportunity quality score (0-100) for a not-yet-submitted AWS co-sell opportunity draft. Runs a deterministic gate (placeholder/empty/product-pitch business problem) that caps the score at 0, then an LLM rubric that returns the predicted score, band, per-dimension breakdown, and prioritized fixes. Use it to show sellers how to improve a referral before submitting. It creates and modifies no referral and writes nothing to the CRM. It does invoke a language model and record AI usage for the organization, so run it when the seller asks how to improve a draft; it is not needed after every edit.

Scope: AWS only. There is no equivalent score for AZURE or GCP opportunities.

How this differs from ValidateReferral: ValidateReferral checks whether the required fields are present and well-formed, and reports same-titled open opportunities. This operation judges how good the narrative content is and returns per-dimension guidance on improving it. Run both before creating an AWS referral.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |

## Request Body

Required.

Content-Type: `application/json` · Schema: `PredictQualityScoreRequest`

**`PredictQualityScoreRequest`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `opportunity` | object | no | Opportunity is the ACE opportunity draft (AceOpportunityV2 shape). |

## Responses

### 200 — Predicted quality score

Content-Type: `application/json` · Schema: `PredictQualityScoreResponse`

**`PredictQualityScoreResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bucket` | string | no | Bucket is the predicted band: LOWEST, LOW, MEDIUM, HIGH, HIGHEST. |
| `dimensions` | array<QualityScoreDimension> | no | Dimensions is the per-rubric-dimension breakdown. |
| `fixes` | array<QualityScoreFix> | no | Fixes are prioritized suggestions, each tagged with the points it adds. |
| `gate` | array<QualityScoreGateIssue> | no | Gate lists deterministic issues; non-empty means Score is 0. |
| `score` | integer | no | Score is the predicted AWS opportunity quality score, 0-100. |
| `verdict` | string | no | Verdict is a one-line human summary. |

**`QualityScoreDimension`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `earned` | integer | no |  |
| `name` | string | no |  |
| `weight` | integer | no |  |

**`QualityScoreFix`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | no | Field is the ACE opportunity field path the fix applies to (e.g. Project.CustomerBusinessProblem, LifeCycle.NextSteps), so the UI can offer to apply a draft or jump to the field. Empty when unknown. |
| `fieldLabel` | string | no | FieldLabel is the form display name of Field (e.g. "Customer business problem"), for showing to sellers instead of the JSON path. |
| `points` | integer | no |  |
| `suggestion` | string | no |  |

**`QualityScoreGateIssue`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | no |  |
| `message` | string | no |  |

### 400 — Bad request error

Content-Type: `application/json` · Schema: `ErrorResponse`

**`ErrorResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | ErrorCode | no |  |
| `info` | object | no |  |
| `message` | string | no |  |

### 500 — Internal server error

Content-Type: `application/json` · Schema: `ErrorResponse`

**`ErrorResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
curl -X POST 'https://api.suger.cloud/org/{orgId}/cosell/referral/predict-quality-score' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### Response — 200

```json
{
  "bucket": "string",
  "dimensions": [
    {
      "earned": 1,
      "name": "Acme Corp",
      "weight": 1
    }
  ],
  "fixes": [
    {
      "field": "string",
      "fieldLabel": "string",
      "points": 1,
      "suggestion": "string"
    }
  ],
  "gate": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "score": 1,
  "verdict": "string"
}
```

### Error — 400

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

---

API reference: https://doc.fours.com/api/