POST/booking-sources/{sourceId}/imports

Queue an initial import of at most 500 booking snapshots

Bearer Tokenbookings:write

participants:writeAt least one imported booking contains the participants property.

Request

curl · Sandboxbash

curl --request POST \
  'https://sandbox-api.padel-lab.crewio.co/v1/club/booking-sources/src_01JABC/imports' \
  --header 'Authorization: Bearer $PADEL_LAB_TOKEN' \
  --header 'Idempotency-Key: 018f-unique-request-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "bookings": [
    {
      "external_booking_id": "booking-1001",
      "booking": {
        "source_version": 1,
        "status": "CONFIRMED",
        "external_court_id": "court-1",
        "scheduled_start": "2030-01-15T18:00:00.000Z",
        "scheduled_end": "2030-01-15T19:30:00.000Z"
      }
    }
  ]
}'

Parameter

sourceIdpathIdrequired

Idempotency-Keyheaderstringrequired

Unique key retained for 24 hours on authenticated mutation endpoints. The installation-exchange binding is retained permanently with its consumed authorization code. Reuse with different request content returns IDEMPOTENCY_CONFLICT.

Request Body

BookingImportInputrequired

Examplejson

{
  "bookings": [
    {
      "external_booking_id": "booking-1001",
      "booking": {
        "source_version": 1,
        "status": "CONFIRMED",
        "external_court_id": "court-1",
        "scheduled_start": "2030-01-15T18:00:00.000Z",
        "scheduled_end": "2030-01-15T19:30:00.000Z"
      }
    }
  ]
}

JSON Schema anzeigen

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "bookings"
  ],
  "properties": {
    "bookings": {
      "type": "array",
      "minItems": 1,
      "maxItems": 500,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "external_booking_id",
          "booking"
        ],
        "properties": {
          "external_booking_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "booking": {
            "type": "object",
            "additionalProperties": false,
            "description": "A complete source-owned snapshot. scheduled_end must be after scheduled_start and the duration must not exceed 24 hours.",
            "required": [
              "source_version",
              "external_court_id",
              "scheduled_start",
              "scheduled_end",
              "status"
            ],
            "properties": {
              "source_version": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2147483647
              },
              "external_court_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "x-runtime-normalization": "trim-before-length-validation"
              },
              "scheduled_start": {
                "type": "string",
                "format": "date-time",
                "description": "UTC RFC 3339 timestamp"
              },
              "scheduled_end": {
                "type": "string",
                "format": "date-time",
                "description": "UTC RFC 3339 timestamp"
              },
              "status": {
                "type": "string",
                "enum": [
                  "CONFIRMED",
                  "CANCELLED",
                  "COMPLETED"
                ]
              },
              "participants": {
                "type": "array",
                "maxItems": 4,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "external_id",
                    "display_name"
                  ],
                  "properties": {
                    "external_id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200,
                      "x-runtime-normalization": "trim-before-length-validation"
                    },
                    "display_name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 80,
                      "x-runtime-normalization": "trim-before-length-validation"
                    },
                    "team": {
                      "type": "string",
                      "enum": [
                        "BLUE",
                        "ORANGE",
                        "UNASSIGNED"
                      ]
                    },
                    "consent_to_share": {
                      "type": "boolean",
                      "default": false,
                      "description": "Explicit consent to expose the data-minimized participant through the Club API. Omission is treated as false."
                    },
                    "consent_reference": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200,
                      "description": "Optional source-side consent receipt or policy reference.",
                      "x-runtime-normalization": "trim-before-length-validation"
                    }
                  },
                  "allOf": [
                    {
                      "if": {
                        "required": [
                          "consent_reference"
                        ]
                      },
                      "then": {
                        "required": [
                          "consent_to_share"
                        ],
                        "properties": {
                          "consent_to_share": {
                            "const": true
                          }
                        }
                      }
                    }
                  ]
                },
                "description": "Requires participants:write in addition to bookings:write."
              }
            }
          }
        }
      }
    }
  }
}

Responses

201Import job created and queuedBookingImportAcceptedResponse

400Malformed JSON or a syntactically valid request that violates a path, query, header or JSON-body constraint.ErrorResponse

401Missing, invalid or expired tokenErrorResponse

403Installation lacks the required scope or is inactiveErrorResponse

404Resource is absent or outside the token-bound tenantErrorResponse

409Version, idempotency, mapping, state or resource-limit conflictErrorResponse

429Rate limit exceededErrorResponse

500An unexpected runtime error occurred; retry only when the operation is safe or idempotent.ErrorResponse

503A required authorization, tenant-safety or rate-limit dependency is unavailableErrorResponse

Response Schemas

BookingImportAcceptedResponseStatus 201

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "status",
        "total",
        "imported",
        "failed",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Opaque stable identifier"
        },
        "status": {
          "type": "string",
          "enum": [
            "PENDING"
          ]
        },
        "total": {
          "type": "integer",
          "minimum": 1,
          "maximum": 500
        },
        "imported": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "UTC RFC 3339 timestamp"
        }
      }
    }
  }
}

ErrorResponseStatus 400, 401, 403, 404, 409, 429, 500, 503

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message",
        "request_id"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable code. Clients must tolerate unknown codes within the same HTTP class.",
          "examples": [
            "invalid_request",
            "invalid_cursor",
            "IDEMPOTENCY_KEY_REQUIRED",
            "unsafe_webhook_url",
            "authentication_required",
            "invalid_token",
            "insufficient_scope",
            "installation_inactive",
            "not_found",
            "VERSION_CONFLICT",
            "UNMAPPED_COURT",
            "IDEMPOTENCY_CONFLICT",
            "IDEMPOTENCY_IN_PROGRESS",
            "endpoint_limit_reached",
            "rate_limited",
            "internal_error",
            "idempotency_replay_failed",
            "authorization_unavailable",
            "rate_limit_unavailable"
          ]
        },
        "message": {
          "type": "string"
        },
        "request_id": {
          "type": "string"
        },
        "details": {}
      }
    }
  }
}