Create Match With AI

This guide helps your team implement POST /api/v1/matches/verified well.

Read this page as a human integration guide first. After you understand the rules, you can copy the AI prompt at the end into ChatGPT, Claude, Cursor, Copilot, or another coding assistant.

Use it if you want to:

• submit completed WPPR verified matches from your own platform
• understand the request rules before writing code
• handle success, duplicate, rejected, validation, auth, and upstream failure cases correctly
• hand a clean, complete prompt to an AI assistant only after you have reviewed the contract yourself

Start here:

• Create match endpoint

Before You Ask AI To Write Code

Make sure a developer on your team can answer these questions first:

• Where does each of the four wppr_id values come from in your platform?
• How do you know whether the match had one, two, or three played sets?
• Where does your club_id mapping come from?
• What should your system do when the API says duplicate?
• Who should see or act on status: rejected reasons?

If your team cannot answer those questions yet, pause there first. AI can help implement the integration, but it should not invent business rules or data mappings for you.

What This Endpoint Does

POST /api/v1/matches/verified creates one completed WPPR verified match per request.

When the submission is accepted, the match is attached to the relevant player profiles, match history, and stats. The API can also tell you that:

• the match was created successfully
• the match already exists as a duplicate
• the submission was rejected because the player mapping or submitted data was not acceptable

Required Request Shape

Every request must include these top-level fields:

• match_id
• team1
• team2
• match_details

Each team must include:

• player1.wppr_id
• player2.wppr_id
• set_1

match_details must include:

• date in YYYY-MM-DD format
• club_id as a real WPPR club UUID

Optional score fields:

• set_2
• set_3

Contract At A Glance

Area	What must be true
Match identity	match_id is your source-system match ID
Players	All four players must have real wppr_id values
Scores	set_1 is required on both teams
Optional sets	set_2 and set_3 are optional, but must be paired across both teams
Match details	match_details.date and match_details.club_id are required
Response handling	Treat created, duplicate, and rejected as distinct business outcomes

Validation Rules You Must Enforce

Before you send a request, make sure your integration follows these rules:

• send exactly one completed match per request
• send four valid player wppr_id values
• never send a placeholder or unplayed match whose submitted set scores are all 0
• never send set_2 for one team without sending it for the other team
• never send set_3 for one team without sending it for the other team
• never send set_3 unless set_2 is also present for both teams
• only send fields supported by the endpoint
• use a real canonical WPPR club_id

Request Examples

Single-set match

{
  "match_id": "13844",
  "team1": {
    "player1": { "wppr_id": "P12B41" },
    "player2": { "wppr_id": "PCD275" },
    "set_1": 4
  },
  "team2": {
    "player1": { "wppr_id": "PB5821" },
    "player2": { "wppr_id": "PF0501" },
    "set_1": 6
  },
  "match_details": {
    "date": "2026-03-23",
    "club_id": "87b2ee5d-1fc6-42be-90bc-ab69d95566a7"
  }
}

Three-set match

{
  "match_id": "13846",
  "team1": {
    "player1": { "wppr_id": "P12B41" },
    "player2": { "wppr_id": "PCD275" },
    "set_1": 4,
    "set_2": 6,
    "set_3": 6
  },
  "team2": {
    "player1": { "wppr_id": "PB5821" },
    "player2": { "wppr_id": "PF0501" },
    "set_1": 6,
    "set_2": 1,
    "set_3": 4
  },
  "match_details": {
    "date": "2026-03-25",
    "club_id": "87b2ee5d-1fc6-42be-90bc-ab69d95566a7"
  }
}

How To Handle Responses

200 OK

The endpoint uses 200 for business-level outcomes:

• status: created means the match was saved
• status: duplicate means the match was already known
• status: rejected means the submission was processed but not accepted

Known rejected reasons already documented:

• missing_wppr_id
• player_not_found:{wppr_id}

Example successful creation:

{
  "source_match_id": "13844",
  "status": "created",
  "match_id": "MC123ABC"
}

Example duplicate:

{
  "source_match_id": "13845",
  "status": "duplicate",
  "match_id": "MC123ABC"
}

Example rejected:

{
  "source_match_id": "14894",
  "status": "rejected",
  "reason": "player_not_found:PDF91DDDD"
}

Error Envelope

All validation, auth, and upstream failures use the same response shape:

{
  "error": true,
  "message": "Invalid or missing API token.",
  "statusCode": 401
}

Outcome Handling Matrix

Outcome	Meaning	Recommended action
status: created	A new match was accepted and saved	Persist the canonical match_id and mark the sync successful
status: duplicate	The match already exists in WPPR	Treat as idempotent success and do not retry
status: rejected	The request was understood but not accepted	Log the reason, notify operations if needed, and fix the source data before retrying
400	Your request shape or values were invalid	Fix your request builder or validation logic
401	Authentication failed	Rotate or correct the bearer token before retrying
404 / 422 / 429 / 5xx	Upstream or platform-level failure	Handle as API failure, not as a business rejection

API Errors You Should Expect

These are transport-level or validation-level errors and should be handled separately from status: rejected.

400 Bad Request

Examples already documented for this endpoint:

• If set_2 is submitted for either team, it must be submitted for both team1 and team2.
• If set_3 is submitted for either team, it must be submitted for both team1 and team2.
• set_3 can only be submitted when set_2 is also submitted for both team1 and team2.
• body/team2/player2 must have required property 'wppr_id'
• Request body contains unsupported fields: [field list]
• The provided club_id does not exist: [club_id]

401 Unauthorized

Examples already documented for this endpoint:

• Authorization header with bearer token is required.
• Invalid or missing API token.

Other upstream and proxy errors

Your integration should also handle:

• 404 when the upstream system cannot find a referenced resource
• 422 when the upstream system rejects the submitted payload as unprocessable
• 429 when the upstream system rate-limits your requests
• 500 for internal proxy failures
• 502 for bad gateway or malformed upstream failures
• 503 when the upstream service is unavailable
• 504 when the upstream service times out

Recommended Implementation Flow

1. Resolve the four canonical wppr_id values and the canonical WPPR club_id.
2. Build the payload with only the sets that were actually played.
3. Validate optional set pairing rules before making the API request.
4. Send the request with bearer authentication from environment variables.
5. Handle created, duplicate, and rejected as business outcomes.
6. Handle 400, 401, 404, 422, 429, and 5xx as API failures.
7. Log enough context for operators to debug a rejected or failed submission later.

Implementation Checklist

Before releasing your integration, verify that:

• your API key is stored in environment variables, not hard-coded
• your request builder only sends set_2 and set_3 when they were actually played
• you validate the optional set rules before making the API request
• club_id comes from the WPPR clubs API or a trusted stored mapping
• duplicate is treated as a known business outcome, not a crash
• rejected reasons are logged and surfaced clearly for operations teams
• 400 validation errors are shown as actionable integration errors
• 401 is handled differently from validation and server errors
• retry logic, if any, is only used for the right classes of upstream failure

Optional: Give This To Your AI Assistant

If your team uses AI to accelerate implementation, use the prompt below only after a human has reviewed the rules above and confirmed the contract with your own team. The prompt is meant to be copied as-is and then customized where marked.

Implement WPPR verified match submission for this endpoint:
https://developers.wecourts.com/api-reference#tag/matches/post/api/v1/matches/verified

Please build this in production-ready code for my stack.

My stack:
- Framework: [replace this]
- Backend language: [replace this]
- Frontend if any: [replace this]

What I need:
- A clean integration for POST /api/v1/matches/verified
- Bearer authentication using environment variables
- Typed request and response models
- Validation before sending the request
- Clear handling for created, duplicate, rejected, validation, auth, and upstream error cases
- Real code, not pseudo code

Endpoint rules:
- Submit one completed match per request
- match_id is my own match ID
- team1 and team2 are required
- each team must include player1.wppr_id and player2.wppr_id
- set_1 is required
- set_2 and set_3 are optional and should only be sent if those sets were played
- if set_2 is sent for one team, it must also be sent for the other team
- if set_3 is sent for one team, it must also be sent for the other team, and set_2 must also be sent for both teams
- match_details is required
- match_details must include date and club_id

Documented outcomes and errors:
- 200 can return status: created, duplicate, or rejected
- documented rejected reasons include missing_wppr_id and player_not_found:{wppr_id}
- 400 can include optional-set validation errors, missing required nested fields, unsupported fields, and invalid club_id
- 401 can include missing bearer auth or an invalid API token
- 404, 422, 429, 500, 502, 503, and 504 should be handled as non-success API failures

Please generate:
- one service or API client method for create match
- request validation
- response parsing
- error handling
- one example controller, route, or frontend submit handler
- one small test example
- short setup instructions

Before coding:
- summarize the plan
- list assumptions
- list files to create or update

Next Steps

• Create match endpoint →
• Best Practices →