Skip to content

Record a win

POST
/v1/contacts/{contact}/wins
curl --request POST \
--url https://api.caller9.app/v1/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/wins \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "studio_guid": "example", "prize": "example" }'

Records a contest win for the contact, timestamped now. Wins count toward the organization’s winner-history eligibility window in Contest Mode.

contact
required
string format: uuid

Contact ID (UUID).

Media typeapplication/json
object
studio_guid
required

Studio the win happened on; must belong to the contact’s organization.

string
<= 64 characters
prize
string | null
<= 255 characters

Example generated

{
"studio_guid": "example",
"prize": "example"
}

The recorded win.

Media typeapplication/json
object
win
required
object
guid
string
studio_guid
string
won_at
string format: date-time
prize
string | null

Example generated

{
"win": {
"guid": "example",
"studio_guid": "example",
"won_at": "2026-04-15T12:00:00Z",
"prize": "example"
}
}

The request was invalid.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.