The Apruvly API is a RESTful JSON API. All requests must be authenticated with an API key. Responses are always JSON unless the response is empty (204).

Base URL

Quick Example

Create a single-step approval workflow with one curl command:

curl -X POST https://api.apruvly.io/api/v1/workflow \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Q1 Marketing Budget",
    "description": "Marketing budget for Q1, $18k total"
  },
  "expires": "48h",
  "start": "step1",
  "workflow": {
    "step1": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Q1 Marketing Budget – $18k",
        "body": "Please review the budget breakdown in the linked document and share your decision."
      }
    }
  }
}'

Pass your API key in the Authorization header as a Bearer token. You can create and manage API keys from the dashboard.

Header format

Authorization: Bearer wf_YOUR_API_KEY

You can generate an API key from the API Keys section in the dashboard.

Creates a new approval workflow and immediately starts the first step.

Request Body

Example Request

curl -X POST https://api.apruvly.io/api/v1/workflow \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Contract Sign-off",
    "description": "Legal review for client contract #4821",
    "links": ["https://drive.example.com/contracts/4821"],
    "tags": ["legal", "contract"]
  },
  "external_id": "CONTRACT-2025-0042",
  "expires": "72h",
  "start": "legal-review",
  "workflow": {
    "legal-review": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Approval Request: Contract #4821",
        "body": "Please review and approve contract #4821."
      },
      "approved": "ceo-approval",
      "escalation": {
        "type": "email",
        "after": "24h",
        "data": {
          "to": ["[email protected]"],
          "subject": "Escalation: Contract #4821 pending approval",
          "body": "Contract #4821 has not been reviewed. Please take action."
        }
      }
    },
    "ceo-approval": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Final Approval: Contract #4821",
        "body": "Legal review is complete. Please provide final approval."
      }
    }
  }
}'

Example Response 202 Accepted

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "CONTRACT-2025-0042"
  }
}

Attach your own business reference (contract number, CRM ticket, deploy id) when creating a workflow, then poll status or cancel without storing the platform UUID. Requires the Growth plan or higher. Max 128 characters; allowed: letters, digits, and . _ : / -. Unique per account.

Example Response 402 Payment Required

{
  "success": false,
  "message": "Your plan does not include external_id. Upgrade to Growth or higher to attach a business correlation id to workflows."
}

Create Workflow — Example Request

curl -X POST https://api.apruvly.io/api/v1/workflow \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Contract Sign-off",
    "description": "Legal review for client contract #4821"
  },
  "external_id": "CONTRACT-2025-0042",
  "expires": "72h",
  "start": "legal-review",
  "workflow": {
    "legal-review": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Approval Request: Contract #4821",
        "body": "Please review and approve contract #4821."
      }
    }
  }
}'

Example Response 202 Accepted

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "CONTRACT-2025-0042"
  }
}

Get by external_id — Example Request

Returns the same payload as GET /workflow/{id}, looked up by the external_id supplied at creation. Requires Growth plan or higher.

curl https://api.apruvly.io/api/v1/workflow/external/CONTRACT-2025-0042 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Example Response 200 OK

{
  "success": true,
  "data": {
    "id":                  "550e8400-e29b-41d4-a716-446655440000",
    "externalId":          "CONTRACT-2025-0042",
    "status":              "pending",
    "currentStep":         "legal-review",
    "createdAt":           "2025-01-15T10:00:00Z",
    "expiresAt":           "2025-01-18T10:00:00Z",
    "decisions": []
  }
}

Cancel Workflow — Example Request

curl -X DELETE https://api.apruvly.io/api/v1/workflow/external/CONTRACT-2025-0042 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Example Response 200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

List Workflows — Example Request

curl "https://api.apruvly.io/api/v1/workflows/search?external_id=CONTRACT-2025-0042" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Example Response 200 OK

{
  "success": true,
  "data": [
    {
      "id":             "550e8400-e29b-41d4-a716-446655440000",
      "title":          "Contract Sign-off",
      "external_id":    "CONTRACT-2025-0042",
      "current_status": "pending",
      "current_step":   "legal-review",
      "created_at":     "2025-01-15T10:00:00Z",
      "expires_at":     "2025-01-18T10:00:00Z",
      "completed_at":   null
    }
  ]
}

Validates a workflow configuration without creating it. Useful for checking your payload before submitting.

Example Request

curl -X POST https://api.apruvly.io/api/v1/workflow/validate \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Test Workflow"
  },
  "expires": "24h",
  "start": "step1",
  "workflow": {
    "step1": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Test Approval",
        "body": "Please approve this test request."
      }
    }
  }
}'

Example Response 200 OK

{
  "success": true
}

Retrieves the full state of a workflow including its activity log and decision history.

Path Parameters

Example Request

curl https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Example Response 200 OK

{
  "success": true,
  "data": {
    "id":                  "550e8400-e29b-41d4-a716-446655440000",
    "externalId":          "CONTRACT-2025-0042",
    "status":              "pending",
    "currentStep":         "ceo-approval",
    "currentEscalation":  0,
    "createdAt":           "2025-01-15T10:00:00Z",
    "expiresAt":           "2025-01-18T10:00:00Z",
    "nextTickAt":          "2025-01-16T10:00:00Z",
    "decisions": [
      {
        "user":        "[email protected]",
        "is_approved": true,
        "ip":          "203.0.113.42",
        "decisionAt":  "2025-01-15T14:22:00Z"
      }
    ]
  }
}

Returns a paginated list of workflows belonging to the authenticated user.

Query Parameters

Example Request

curl "https://api.apruvly.io/api/v1/workflows/search?status=pending&query=contract" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Example Response 200 OK

{
  "success": true,
  "data": [
    {
      "id":             "550e8400-e29b-41d4-a716-446655440000",
      "title":          "Contract Sign-off",
      "external_id":    "CONTRACT-2025-0042",
      "current_status": "pending",
      "current_step":   "ceo-approval",
      "created_at":     "2025-01-15T10:00:00Z",
      "expires_at":     "2025-01-18T10:00:00Z",
      "completed_at":   null
    }
  ]
}

Returns the most recently created workflows for the authenticated user.

Example Request

curl "https://api.apruvly.io/api/v1/workflows/recent" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Returns the authenticated user's subscription, plan, credit balance and usage summary.

Example Request

curl "https://api.apruvly.io/api/v1/billing" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Manage third-party channel credentials (Slack, MS Teams, Twilio, etc.) via the REST API.

Cancels a pending workflow. Completed or expired workflows cannot be canceled.

You can also cancel by the business id you set at creation time — see Business correlation IDs (external_id). Business correlation IDs (external_id)

Path Parameters

Example Request

curl -X DELETE https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Example Response 200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Records an approval or rejection decision for a workflow step. The action (approve or reject) is determined by the URL path suffix, not the request body. No request body is required.

Path Parameters

Example Request

# Approve
curl -X PUT https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000/7a9f1c2d-4b3e-48f6-9d8c-1a2b3c4d5e6f/approve \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

# Reject
curl -X PUT https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000/7a9f1c2d-4b3e-48f6-9d8c-1a2b3c4d5e6f/reject \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Example Response 200 OK

{
  "success": true
}

Manage your address book of areas (teams) and people. Contacts feed email fallback at notification time and link recipients for cross-channel analytics.

Areas

People

Example Request — Create a person with memberships and contacts.

curl -X POST https://api.apruvly.io/api/v1/directory/people \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Ana Souza",
    "area_ids": ["6c2b6e80-1f74-4cf2-9e2f-0d0e3b9b0001"],
    "contacts": [
      { "provider": "email", "address": "[email protected]", "label": "work" },
      { "provider": "twilio-sms", "address": "+5511999999999" }
    ]
  }'

Example Response 201 Created

{
  "success": true,
  "data": {
    "id": "a4d1f0c6-2d24-49b3-9e3c-7a2e6c4b0001",
    "display_name": "Ana Souza",
    "is_active": true,
    "area_ids": ["6c2b6e80-1f74-4cf2-9e2f-0d0e3b9b0001"],
    "contacts": [
      { "id": "…", "provider": "email", "address": "[email protected]", "label": "work" },
      { "id": "…", "provider": "twilio-sms", "address": "+5511999999999" }
    ]
  }
}

Bulk operations

Bulk endpoints accept an array of items under a single "items" field. Creation is capped per request (100 areas, 1,000 people) and updates are limited to twice the customer's plan size for the relevant resource.

Example Request — Create up to 1,000 people in a single call (with their memberships and contacts).

curl -X POST https://api.apruvly.io/api/v1/directory/people/bulk \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "display_name": "Ana Souza",
        "area_ids": ["6c2b6e80-1f74-4cf2-9e2f-0d0e3b9b0001"],
        "contacts": [
          { "provider": "email", "address": "[email protected]", "label": "work" }
        ]
      },
      {
        "display_name": "Bruno Lima",
        "contacts": [
          { "provider": "twilio-sms", "address": "+5511988887777" }
        ]
      }
    ]
  }'

Example Response 201 Created

{
  "success": true,
  "data": {
    "count": 2,
    "items": [
      { "id": "a4d1f0c6-…", "display_name": "Ana Souza", "area_ids": ["6c2b6e80-…"], "contacts": ["…"] },
      { "id": "f10b2e8a-…", "display_name": "Bruno Lima", "area_ids": [], "contacts": ["…"] }
    ]
  }
}

The whole batch is processed together: if any single entry is invalid the request is rejected and nothing is saved.

Required scopes

Each endpoint requires the matching API key scope. Grant scopes under API Keys in the console.

Contact address formats

Each contact is a (provider, address) pair. Only providers configured under /integrations (plus email) are accepted.

DingTalk group robots are not stored in the directory — they broadcast to a group, not an individual contact.

Errors

Use the `on` field to register actions for workflow lifecycle events. Each action has a type (webhook, email, or twilio-sms) and a data payload. When an event fires, all actions are executed in order.

Wrapped and flat forms

Each action is a JSON object that can be serialized in two forms. The wrapped form ({"type":"...", "data":{...}}) is the canonical form produced by the API and the only one accepted for twilio-sms. The flat form infers the type from the payload fields (url → webhook, to → email) and is kept for backward compatibility.

{
  "on": {
    "workflow_approved": [
      { "type": "webhook",    "data": { "url": "https://example.com/hooks/approved", "method": "POST" } },
      { "type": "email",      "data": { "to": ["[email protected]"], "subject": "Approved", "body": "Workflow ${id} is approved." } },
      { "type": "twilio-sms", "data": { "to": ["+14155552671"], "body": "Workflow ${id} approved" } }
    ]
  }
}

Lifecycle events

WebhookAction — type: "webhook"

Sends an HTTP request to an external endpoint. Private and loopback hosts are rejected at dispatch time.

EmailAction — type: "email"

Sends an email through your custom SMTP (when configured) or the system postman.

SmsAction — type: "twilio-sms"

Sends a fire-and-forget SMS through Twilio. Informational only — no short-code correlation or reply tracking.

Variable Interpolation

You can use the following variables inside webhook body values. They are automatically replaced at execution time.

Example Request

{
  "on": {
    "workflow_approved": [
      {
        "type": "webhook",
        "data": {
          "url":     "https://api.yourapp.com/webhooks/approved",
          "method":  "POST",
          "headers": { "Authorization": "Bearer your-token" },
          "body": {
            "workflow_id":  "${id}",
            "status":       "${status}",
            "current_step": "${current_step}"
          },
          "timeout": "30s"
        }
      }
    ],
    "workflow_rejected": [
      {
        "type": "webhook",
        "data": {
          "url":   "https://api.yourapp.com/webhooks/rejected",
          "async": true
        }
      }
    ],
    "step_approved": [
      {
        "type": "webhook",
        "data": {
          "url":  "https://api.yourapp.com/webhooks/step-done",
          "body": {
            "step": "${current_step}"
          }
        }
      }
    ]
  }
}

Per-step actions

In addition to workflow-level events, each step can register its own actions that fire when THAT step is approved or rejected — independent of the final workflow outcome. Use `step.actions.approved` and `step.actions.rejected` to trigger webhooks or emails per decision.

{
  "workflow": {
    "review": {
      "type": "email",
      "data": {
        "to":      ["[email protected]"],
        "subject": "Please review",
        "body":    "Approve or reject ${id}"
      },
      "actions": {
        "approved": [
          {
            "type": "webhook",
            "data": {
              "url":    "https://example.com/hooks/review-approved",
              "method": "POST"
            }
          }
        ],
        "rejected": [
          {
            "type": "email",
            "data": {
              "to":      ["[email protected]"],
              "subject": "Review rejected",
              "body":    "${id} was rejected"
            }
          }
        ]
      }
    }
  }
}

Cost: each webhook counts as 1 credit; each recipient in email or twilio-sms actions counts as 1 credit per recipient. CC and BCC on email actions are not charged.

Credit cost

Each step costs 1 credit plus 1 per configured escalation level. External delivery actions add a single flat surcharge shared between webhook and twilio-sms.

Credits are debited once at workflow creation time. There is no per-dispatch charge.

Step

Channel delivery

Shared channel delivery posts one approval message to a team channel, group, or chat. Only users listed in allowList can click the interactive Approve/Reject buttons; the decision log records the clicker, not the channel ID.

CardOverride

EmailData — used when type = email

Email body variables

These placeholders can be used in the subject and body fields.

SlackData — used when type = slack

MSTeamsData — used when type = ms-teams

WhatsAppData — used when type = whatsapp

TelegramData — used when type = telegram

DiscordData — used when type = discord

DingTalkData — used when type = dingtalk

TwilioSMSData — used when type = twilio-sms

TwilioWhatsAppData — used when type = twilio-whatsapp

Escalation

Decision — returned inside decisions[] in GET /workflow/{id}

Custom SMTP (account integration)

Business and Professional plans can send approval emails through your own SMTP server instead of the platform mailer. Configure it under Settings → Integrations → Custom SMTP (not in the workflow JSON).

• Host, port, From address, and optional username/password. Use Send Test Email before saving production workflows.
• Port 587 with STARTTLS (TLS switch off) or port 465 with implicit TLS (TLS switch on). Private and reserved IP targets are blocked.
• Use a From address your server is allowed to relay (typically a mailbox on a domain you authenticate with SPF/DKIM).
• Credentials are encrypted at rest (AES-256-GCM). Outbound connections require TLS 1.2+. Test emails are sent only to your account email.
• Delivery, bounces, and SPF/DKIM/DMARC alignment are enforced by your SMTP server — Apruvly does not verify your sending domain.

Step Identifier Rules

Step keys (used in start, approved and rejected fields, and as workflow map keys) must match the following pattern - lowercase letter followed by lowercase letters, digits, hyphens or underscores:

Duration Format

Durations are expressed as a number followed by a unit suffix:

Workflow expiration must be between 5 minutes (minimum) and 7 days (maximum).

The MCP endpoint follows the Model Context Protocol specification using JSON-RPC 2.0 over HTTP. It allows AI agents and automation tools to pause execution and request human approval before taking critical actions.

Endpoint

Authentication Required

Authorization: Bearer wf_YOUR_API_KEY
Content-Type: application/json

Discovery Optional

MCP-aware clients can fetch a public discovery document at GET /.well-known/mcp to auto-detect the endpoint URL, supported transports and protocol versions, the auth scheme, and the catalog of available tools. No authentication required.

{
  "endpoint": "https://mcp.apruvly.io/mcp",
  "transports": ["streamable-http"],
  "protocolVersions": ["2025-03-26"],
  "auth": { "scheme": "bearer" },
  "tools": ["create_approval_request", "get_approval_status", "cancel_approval_request"]
}

How it works

• Claude Code
• Claude Desktop
• Cursor
• VS Code
• curl

{
  "mcpServers": {
    "apruvly": {
      "type": "streamable-http",
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "apruvly": {
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "apruvly": {
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

// .vscode/mcp.json
{
  "servers": {
    "apruvly": {
      "type": "http",
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

curl -X POST https://mcp.apruvly.io/mcp \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": {"name": "my-agent", "version": "1.0"},
      "capabilities": {}
    }
  }'