--- updatedAt: 2026-08-14T06:33:42.000Z agentTools: projectIndex: https://docs.developers.convert.com/llms.txt --- # Approve a pending approval request Approves a pending request, recording `reviewed_by` and `reviewed_at`. Returns `403 Forbidden` if the caller is the submitter (self-approval is not permitted) and `422 Unprocessable Entity` if the request is not in `pending` state. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Convert Management API", "description": "Move your app forward with the Convert API. The Convert API allows\nyou to manage your Convert Experiences projects using code. The REST API is\nan interface for managing and extending functionality of Convert. For\nexample, instead of creating and maintaining projects using the Convert\nExperiences web dashboard you can create an experiment programmatically.\nAdditionally, if you prefer to run custom analysis on experiment results you\ncan leverage the API to pull data from Convert Experiences into your own\nworkflow. If you do not have a Convert account already, sign up for a free\ndeveloper account at https://www.convert.com/api/.\n\n*[Convert API V1](/doc/v1) is still available and documentation can be found [here](/doc/v1) but using it is highly discouraged\nas it will be phased out in the future*\n", "version": "2.0.0" }, "x-tagGroups": [ { "name": "Client Authentication", "tags": [ "API KEY Authentication", "Cookie Authentication", "OAuth Authorization" ] }, { "name": "Common Parameters", "tags": [ "Optional Fields", "Expandable Fields" ] }, { "name": "Requests", "tags": [ "User", "Accounts", "AI content", "Collaborators", "API Keys", "Notifications", "Projects", "SDK Keys", "Experiences", "Experience Variations", "Experience Sections", "Section Versions", "Version Changes", "Experiences Reports", "Experiences Heatmaps", "Goals", "Hypotheses", "Knowledge Bases", "Observations", "Locations", "Audiences", "Domains", "Cdn Images", "Files", "Tags", "Features", "Visitor Insights", "Visitors Data", "Visitor Data Placeholders", "OAuth", "Approval Requests" ] } ], "tags": [ { "name": "Approval Requests", "description": "The Approval Requests system is a generic, entity-agnostic approval workflow framework. It lets accounts gate sensitive actions (e.g., activating, pausing, or modifying a running experience) behind an approval step. Submitters create requests; eligible approvers (never the submitter) approve or reject them; the backend enforces the rules at the service layer.\n" } ], "paths": { "/accounts/{account_id}/approval-requests/{request_id}/approve": { "post": { "operationId": "approveApprovalRequest", "x-mutates": true, "summary": "Approve a pending approval request", "description": "Approves a pending request, recording `reviewed_by` and `reviewed_at`. Returns `403 Forbidden`\nif the caller is the submitter (self-approval is not permitted) and `422 Unprocessable Entity`\nif the request is not in `pending` state.\n", "tags": [ "Approval Requests" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "ID of the account that owns the approval request.", "schema": { "type": "integer" } }, { "name": "request_id", "in": "path", "required": true, "description": "UUID of the approval request.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/ApproveApprovalRequest" }, "responses": { "200": { "$ref": "#/components/responses/ApprovalRequestResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "422": { "$ref": "#/components/responses/ErrorResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.convert.com/api/v2", "description": "Live API server" }, { "url": "https://apidev.convert.com/api/v2", "description": "DEV API server" }, { "url": "http://apidev.convert.com:5000/api/v2", "description": "DEV mocked API server" } ], "components": { "securitySchemes": { "secretKey": { "type": "http", "scheme": "bearer", "description": "See **[API Key Authentication](/reference/api-key-authentication)** for more information.\n" }, "cookieAuthentication": { "type": "apiKey", "in": "cookie", "name": "sid", "description": "Cookie authentication is used against Convert's own IdentityProvider or third party identity providers and is described more in the \"[Cookie Authentication](/reference/cookie-authentication)\" section" }, "requestSigningAppId": { "type": "apiKey", "in": "header", "name": "Convert-Application-ID", "description": "HMAC request signing — the Application ID from your Convert account. See **[API Key Authentication](/reference/api-key-authentication)** for how to generate the full three-header set." }, "requestSigningExpires": { "type": "apiKey", "in": "header", "name": "Expires", "description": "HMAC request signing — UNIX timestamp after which the signature expires. See **[API Key Authentication](/reference/api-key-authentication)** for how to compute it." }, "requestSigningAuthorization": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "HMAC request signing — format: `Convert-HMAC-SHA256 Signature=`. See **[API Key Authentication](/reference/api-key-authentication)** for the signing algorithm. The \"Try It\" playground cannot compute this for you; paste a pre-computed signature here or use the Bearer method instead." } }, "requestBodies": { "ApproveApprovalRequest": { "required": false, "description": "Optionally supplies a reason when approving a pending request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveApprovalRequestData" } } } } }, "responses": { "ErrorResponse": { "description": "Indicates an error occurred while processing the request. The `code` provides an HTTP status code, `message` offers a human-readable explanation or an array of validation errors, and `fields` (if present) specifies which input fields were problematic.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorData" } } } }, "ApprovalRequestResponse": { "description": "A single approval request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequest" } } } } }, "schemas": { "ApprovalRequestStatus": { "type": "string", "description": "Lifecycle state of an approval request.", "enum": [ "pending", "approved", "rejected" ] }, "ApprovalRequestRuleCode": { "type": "string", "description": "Code of a predefined approval rule. Each value maps to an entity type and a specific\naction (e.g., `experience.activate`).\n", "enum": [ "experience.activate", "experience.pause", "experience.modify_while_active" ] }, "ApprovalRequestEntityType": { "type": "string", "description": "Type of entity an approval rule or request applies to (e.g., `experience`).", "enum": [ "experience" ] }, "ApprovalRequestUser": { "type": "object", "description": "Resolved user reference returned for `submitted_by` / `reviewed_by` when the\ncorresponding field is requested via `include`.\n", "properties": { "uid": { "type": "string", "description": "User ID." }, "name": { "type": "string", "nullable": true, "description": "User full name, or null when unknown." } } }, "ApprovalRequest": { "type": "object", "description": "A single approval request governing an action on an entity. Created in `pending` state by a\nsubmitter, then approved or rejected by an eligible approver (never the submitter). When an\napproved request is consumed by a successful action, `consumed_at` is set.\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique request identifier (UUID)." }, "entity_type": { "$ref": "#/components/schemas/ApprovalRequestEntityType" }, "entity_id": { "type": "string", "description": "ID of the entity being acted on." }, "project_id": { "type": "string", "nullable": true, "description": "ID of the project that owns the entity being acted on, or null when the entity is not project-scoped. Required for project-scoped entity types." }, "rule_code": { "$ref": "#/components/schemas/ApprovalRequestRuleCode" }, "status": { "$ref": "#/components/schemas/ApprovalRequestStatus" }, "submitted_by": { "description": "Submitter of the request. A plain user-id string by default, or a\n`{ uid, name }` object when `submitted_by` is requested via `include`.\n", "oneOf": [ { "type": "string", "description": "User ID of the submitter." }, { "$ref": "#/components/schemas/ApprovalRequestUser" } ] }, "submitted_at": { "type": "string", "format": "date-time", "description": "When the request was created." }, "context": { "type": "string", "nullable": true, "description": "Optional submitter-provided context (plain text or serialized JSON)." }, "reviewed_by": { "nullable": true, "description": "Approver/rejector of the request. Null until reviewed. A plain user-id\nstring by default, or a `{ uid, name }` object when `reviewed_by` is\nrequested via `include`.\n", "oneOf": [ { "type": "string", "description": "User ID of the approver/rejector." }, { "$ref": "#/components/schemas/ApprovalRequestUser" } ] }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the review action occurred. Null until reviewed." }, "review_reason": { "type": "string", "nullable": true, "description": "Reviewer's reason. Required on rejection." }, "consumed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When an approved request was consumed by a successful action execution. Null until consumed.\nA non-null value distinguishes \"approved and acted on\" from \"approved but not yet executed\".\n" } }, "required": [ "id", "entity_type", "entity_id", "rule_code", "status", "submitted_by", "submitted_at" ] }, "ApproveApprovalRequestData": { "type": "object", "description": "Optional payload for approving a request.", "properties": { "reason": { "type": "string", "description": "Optional reason for the approval." } } }, "ErrorData": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "fields": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "context": { "type": "object", "description": "Additional context about the error." } } } } }, "security": [ { "requestSigningAppId": [], "requestSigningExpires": [], "requestSigningAuthorization": [] }, { "secretKey": [] }, { "cookieAuthentication": [] } ] } ```