> ## Documentation Index > Fetch the complete documentation index at: https://broker-docs.newyorkcityservers.com/llms.txt > Use this file to discover all available pages before exploring further. # Manage Request > Approve or deny a pending service request. Approve or deny one pending request in your broker account. Use the public request ID from the [list requests endpoint](/api/requests/list-requests). | Request type | Approval operation | HTTP `200` request status | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `new-service` | Creates or reuses a pending service and queues a service creation action. The worker provisions the service and runs enabled invoice, welcome-email, follow-up, and setup-notification operations. | `approved` | | `cancellation` | Queues a cancellation action. The worker processes the upstream cancellation and local service changes. | `accepted` | | `upgrade` or `downgrade` | Queues a plan-change action. The worker processes the upstream plan change and local service changes. | `approved` | | `welcome-email` | Tries the welcome-email resend during the approval call. | `approved` | | Other pending request types | Records the request approval. | `approved` | ## Errors All error responses use `success: false` and an `error` object. | HTTP status | Error code | Cause | | ----------- | -------------------------- | ---------------------------------------------------------------------------------------- | | `400` | `invalid_parameter` | The request ID format or action is invalid. | | `400` | `invalid_request` | The request body is not valid JSON. | | `400` | `missing_parameter` | A denial has no nonblank `denial_reason`. | | `401` | `authentication_failed` | The Bearer token is missing, invalid, inactive, or expired. | | `403` | `insufficient_permissions` | The caller IP is not allowed, or the key does not have `requests:write` or `admin:full`. | | `404` | `not_found` | The request does not exist in this broker account. | | `409` | `already_processed` | The request is not `pending`, or another caller processed it first. | | `429` | `rate_limit_exceeded` | The API key reached its rate limit. Check the `Retry-After` header. | | `500` | `server_error` | The denial update or another internal operation failed. | An `already_processed` response can include the request's current stored state. ## OpenAPI ````yaml api/openapi.yaml POST /v1/requests/{request_id}/manage openapi: 3.1.0 info: title: Broker API version: 1.0.0 description: API for broker-scoped service, request, and report operations. servers: - url: https://brokers.newyorkcityservers.com/api description: Broker Panel API security: - bearerAuth: [] tags: - name: Authentication - name: Services - name: Requests - name: Reports paths: /v1/requests/{request_id}/manage: post: tags: - Requests summary: Manage Request description: >- Approves or denies one pending broker-owned request. Requires `requests:write` or `admin:full`. operationId: manageRequest parameters: - $ref: '#/components/parameters/RequestId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ManageRequestBody' examples: approve: value: action: approve deny: value: action: deny denial_reason: Account verification is incomplete responses: '200': description: Request approved, accepted, or denied. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/ManageRequestResult' examples: approved: value: success: true data: request_id: REQ-002167 request_status: approved service_number: 30502 denied: value: success: true data: request_id: REQ-002167 request_status: denied denial_reason: Account verification is incomplete processed_date: '2026-06-21T15:00:00.000Z' '202': description: Approval accepted for NYCServers review. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/ReviewResult' example: success: true data: request_id: REQ-002167 request_status: nycservers_review message: >- There was a setup issue. Your request is now under admin review—no need to resubmit. The service will be delivered to the client shortly. service_number: 30502 service_status: pending '400': description: >- Codes `invalid_parameter`, `invalid_request`, or `missing_parameter`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidAction: value: success: false error: code: invalid_parameter message: Invalid action details: valid_values: - approve - deny missingDenialReason: value: success: false error: code: missing_parameter message: Missing denial_reason for deny action details: required_fields: - denial_reason '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '404': description: Code `not_found` when no broker-owned request matches. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: not_found message: Request not found or access denied '409': description: >- Code `already_processed` when the request is no longer pending or loses a concurrent update race. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: already_processed message: Request is already processed details: current_status: approved '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/ServerError' components: parameters: RequestId: name: request_id in: path required: true description: >- Public request ID in REQ- followed by digits format; matching is case-insensitive. schema: type: string pattern: ^[Rr][Ee][Qq]-[0-9]+$ example: REQ-002167 schemas: ManageRequestBody: type: object required: - action properties: action: type: string enum: - approve - deny description: Accepted case-insensitively after trimming. denial_reason: type: string minLength: 1 description: Required and nonblank when action is deny. SuccessEnvelope: type: object required: - success properties: success: type: boolean const: true message: type: string pagination: $ref: '#/components/schemas/Pagination' ManageRequestResult: type: object required: - request_id - request_status properties: request_id: type: string request_status: type: string enum: - approved - accepted - denied service_number: type: - integer - 'null' service_status: type: string const: pending message: type: string denial_reason: type: string processed_date: type: string format: date-time ReviewResult: type: object required: - request_id - request_status - message properties: request_id: type: - string - 'null' request_status: type: string enum: - pending - processing - nycservers_review message: type: string service_number: type: - integer - 'null' service_status: type: string const: pending ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/Error' Pagination: type: object required: - page - perPage - total - totalPages properties: page: type: integer minimum: 1 perPage: type: integer minimum: 1 maximum: 100 total: type: integer minimum: 0 totalPages: type: integer minimum: 0 Error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true responses: AuthenticationError: description: >- Code `authentication_failed` for a missing, malformed, invalid, inactive, or expired API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: authentication_failed message: Invalid API key PermissionError: description: >- Code `insufficient_permissions` when the request IP is not whitelisted or a required scope is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: insufficient_permissions message: IP address not whitelisted RateLimitError: description: Code `rate_limit_exceeded` when the API key exceeds its rate limit. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: rate_limit_exceeded message: Rate limit exceeded ServerError: description: >- Code `server_error` when authentication or internal processing cannot complete. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: server_error message: Internal server error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Send the API key in the Authorization bearer header. Production keys begin with `sk_live_`. ````