> ## Documentation Index > Fetch the complete documentation index at: https://docs.dotportion.com/llms.txt > Use this file to discover all available pages before exploring further. # Revoke an invitation > Kills the candidate's magic link immediately. A revoked invitation reads as `expired` in later responses: we force its expiry rather than carrying a separate status. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/invitations/{id}/revoke openapi: 3.1.0 info: title: Dotportion API version: 1.0.0 description: >- Create assessments, invite candidates, and pull back hiring reports. Authenticate with an API key as a bearer token. Keys are scoped to a single organization and cannot reach another one. Use a `sk_test_` key to develop against deterministic sample data. servers: - url: https://app.dotportion.com description: Production security: - bearerAuth: [] tags: - name: Challenges description: The challenge library available to you. - name: Assessments description: Job postings built from a challenge. - name: Invitations description: Candidate invitations and their lifecycle. - name: Submissions description: Candidate attempts, reports and event logs. - name: Members description: Your organization’s team. - name: Account description: Plan, usage and branding. paths: /api/v1/invitations/{id}/revoke: post: tags: - Invitations summary: Revoke an invitation description: >- Kills the candidate's magic link immediately. A revoked invitation reads as `expired` in later responses: we force its expiry rather than carrying a separate status. operationId: revokeInvitation parameters: - name: id in: path required: true description: The invitation id. schema: type: string format: uuid responses: '204': description: Success. No body. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': description: >- INVALID_INPUT — The candidate already submitted — that submission stands. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INVALID_INPUT message: Invalid request details: formErrors: [] fieldErrors: name: - String must contain at least 1 character(s) request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '401': description: INVALID_TOKEN — The key is missing, malformed, revoked, or expired. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INVALID_TOKEN message: Invalid or revoked API key request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '403': description: >- INSUFFICIENT_SCOPE — The key doesn't carry the scope this endpoint needs. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INSUFFICIENT_SCOPE message: 'This API key lacks the required scope: write.' request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '404': description: >- NOT_FOUND — No such resource, it belongs to another organization, or the id isn't a UUID — all indistinguishable by design. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: NOT_FOUND message: Resource not found request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '429': description: RATE_LIMITED — The key exhausted its hourly quota for this class. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: RATE_LIMITED message: >- Rate limit exceeded for write requests (200/hour). Retry after 2026-01-15T13:00:00.000Z. details: limit: 200 remaining: 0 reset: 1768482000 request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c '500': description: INTERNAL_ERROR — Something failed on our side. Quote the request_id. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: INTERNAL_ERROR message: Internal server error request_id: req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c security: - bearerAuth: [] components: headers: XRequestId: description: Correlation id for this request. Quote it in support requests. schema: type: string XRateLimitLimit: description: Requests permitted per hour for this quota class. schema: type: integer XRateLimitRemaining: description: Requests left in the current window. schema: type: integer XRateLimitReset: description: Unix time (seconds) when the window resets. schema: type: integer RetryAfter: description: Seconds to wait before retrying. Present on 429. schema: type: integer schemas: ErrorEnvelope: type: object description: Every failure. Switch on `error.code`, not on the message. properties: error: type: object properties: code: type: string enum: - INVALID_INPUT - INVALID_TOKEN - PLAN_LIMIT_REACHED - INSUFFICIENT_SCOPE - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR description: Stable machine-readable code. message: type: string description: Human-readable. May be reworded. details: description: Field-level validation errors, when applicable. request_id: type: string required: - code - message - request_id required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your API key, live (`sk_live_…`) or test (`sk_test_…`). Create one in Settings → API keys. Send it as `Authorization: Bearer ` — never in a query string. ````