---
title: "Create a bulk pairing"
method: POST
path: "/api/bulk-pairing"
tags: ["Bulk pairings"]
---

# Create a bulk pairing

`POST /api/bulk-pairing`

Schedule many games at once, up to 24h in advance.
OAuth tokens are required for all paired players, with the `challenge:write` scope.
You can schedule up to 500 games every 10 minutes. [Contact us](mailto:contact@lichess.org) if you need higher limits.
If games have a real-time clock, each player must have only one pairing.
For correspondence games, players can have multiple pairings within the same bulk.

**The entire bulk is rejected if:**
  - a token is missing
  - a token is present more than once (except in correspondence)
  - a token lacks the `challenge:write` scope
  - a player account is closed
  - a player is paired more than once (except in correspondence)
  - a bulk is already scheduled to start at the same time with the same player
  - you have 20 scheduled bulks
  - you have 1000 scheduled games

Partial bulks are never created. Either it all fails, or it all succeeds.
When it fails, it does so with an error message explaining the issue.
Failed bulks are not counted in the rate limiting, they are free.
Fix the issues, manually or programmatically, then retry to schedule the bulk.
A successful bulk creation returns a JSON bulk document. Its ID can be used for further operations.

## Response `200`

The bulk pairing has been successfully created.

- BulkPairing
  - `id` string, required
  - `games` object[], required
    - `id` string
    - `black` string
    - `white` string
  - `variant` 'standard' | 'chess960' | 'crazyhouse' | 'antichess' | 'atomic' | 'horde' | 'kingOfTheHill' | 'racingKings' | 'threeCheck' | 'fromPosition', required
  - `clock` Clock, required
    - `limit` integer, required
    - `increment` integer, required
  - `pairAt` integer, required
  - `pairedAt` integer, nullable, required
  - `rated` boolean, required
  - `startClocksAt` integer, required
  - `scheduledAt` integer, required

## Other responses

- `400` — The creation of the bulk pairings failed.

---

[API](https://skmtc.net/lichess/apis/lichess-org-api-reference.md) · [All operations](https://skmtc.net/lichess/apis/lichess-org-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lichess/lichess-org-api-reference/revisions/f16676f55a94/schema)