> ## Documentation Index > Fetch the complete documentation index at: https://docs.teamcaredental.com/llms.txt > Use this file to discover all available pages before exploring further. # Request a slot > Requests (or refreshes) a data-access slot for a location the firm can access, and returns a `request_key` to send in the `X-Vendor-Request-Key` header on data endpoints. - **Validity:** the `request_key` is valid for **6 hours** (the access token's lifetime), after which you must request a new slot. - **Cooldown:** the same location's slot can be re-requested only once every **2 minutes**; within the cooldown this returns `429` with `retry_after` (seconds). - **Rate limit:** 10 requests / 10 seconds per token. - **Quota:** at most `concurrent_slots` (default 10) request keys stay active per firm; the oldest is trimmed when you exceed it, and requests still using that key fail with `401`. Contact TeamCare support to raise the quota. ## OpenAPI ````yaml https://app.teamcaredental.com/openapi-vendors-v2.json post /locations/{location_id}/slots openapi: 3.1.0 info: title: TeamCare Vendor API (v2) version: 2.0.0 description: >- Version 2 of the TeamCare Vendor API. HIPAA-compliant and opt-in. ## What changed from v1 The data endpoints and response shapes are identical to v1 — **only how you address a location changes.** In v1 the location lived in every URL (`/locations/{location_id}/patients`). In v2 you request a **slot** for a location once, then send the returned `request_key` in the `X-Vendor-Request-Key` header; `location_id` is gone from the data routes. ## Request cycle 1. `POST /auth/token` → JWT (unchanged from v1). 2. `GET /organizations`, `GET /locations` → pick a `location_id`. 3. `POST /locations/{location_id}/slots` → `{ request_key, expires_at }`. 4. Call any data endpoint with header `X-Vendor-Request-Key: ` (no `location_id` in the path). ## Minimal changes to migrate - Point your base URL at `https://api.teamcaredental.com/api/v2/vendors` (v2 is served from `api.teamcaredental.com`, not `app.teamcaredental.com`). - Call the slot endpoint **once per location**. - Drop `/locations/{location_id}` from your data paths and add the `X-Vendor-Request-Key` header. - Everything else — authentication, Ransack `q` filters, pagination, response shapes — is unchanged. ## Slot validity, cooldown & quota - **Validity:** a `request_key` is valid for **6 hours** — the same lifetime as the access token. After that it stops authorizing and you must request a new slot. - **Cooldown:** you can only re-request the **same** location's slot once every **2 minutes**. Within the cooldown the slot endpoint returns `429` with a `retry_after` (seconds). - **Quota:** each firm may hold up to its `concurrent_slots` quota (default **10**) active request keys at once, so data for at most 10 locations can be pulled concurrently. Requesting an 11th slot trims the oldest key, so its `request_key` stops authorizing immediately and any in-flight requests using it fail with `401`. To raise the quota above 10, contact TeamCare support. - **Rate limit:** the slot endpoint accepts at most 10 requests per 10 seconds per token. ## Recommended usage Request a slot for a location and pull **all** of that location's data in one pass before moving on — don't re-request slots per call or churn between locations. If you fan out across locations in parallel, keep the fan-out at or below your quota: once an 11th slot is requested, the oldest `request_key` is invalidated even if a sync is still running on it. See the [changelog](https://docs.teamcaredental.com/changelog) for the full list of changes from v1. servers: - url: https://api.teamcaredental.com/api/v2/vendors security: - bearerAuth: [] paths: /locations/{location_id}/slots: post: tags: - Slots summary: Request a slot description: >- Requests (or refreshes) a data-access slot for a location the firm can access, and returns a `request_key` to send in the `X-Vendor-Request-Key` header on data endpoints. - **Validity:** the `request_key` is valid for **6 hours** (the access token's lifetime), after which you must request a new slot. - **Cooldown:** the same location's slot can be re-requested only once every **2 minutes**; within the cooldown this returns `429` with `retry_after` (seconds). - **Rate limit:** 10 requests / 10 seconds per token. - **Quota:** at most `concurrent_slots` (default 10) request keys stay active per firm; the oldest is trimmed when you exceed it, and requests still using that key fail with `401`. Contact TeamCare support to raise the quota. operationId: locations_slots_create parameters: - name: location_id in: path required: true description: The ID of the location (practice) to request a slot for. schema: type: string example: '58' responses: '201': description: Slot created or refreshed. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string example: slot attributes: type: object properties: request_key: type: string example: a1292639f455cf0 requested_at: type: string format: date-time expires_at: type: string format: date-time example: data: id: '1' type: slot attributes: request_key: a1292639f455cf0 requested_at: '2026-10-26T12:00:00.000Z' expires_at: '2026-10-26T18:00:00.000Z' '401': description: Missing, invalid or expired token. content: application/json: schema: type: object properties: errors: type: string example: errors: not authorized '404': description: Location not found or not accessible. content: application/json: schema: type: object properties: errors: type: string example: errors: resource not found '422': description: Validation failed. content: application/json: schema: type: object properties: errors: type: string example: errors: ... '429': description: Rate limit (10 / 10s) or cooldown (2 min) exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: type: object properties: errors: type: array items: type: string retry_after: type: integer example: errors: - >- Slot for this location was requested too recently. Try again in 120s. retry_after: 120 security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT returned by POST /auth/token. Valid for six hours. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.