Portfolio / API Documentation / Reference

ZipFlow REST API v2.0

Complete API reference for integrating with the ZipFlow procurement platform. Build custom integrations, automate workflows, and connect with your existing systems.

🔧 15 Endpoints
📖 1,500 words
🎯 Developers

Base URL

https://api.zipflow.com/v2

Authentication

Bearer Token

Rate Limit

1000 requests/hour

Overview

The ZipFlow API is a RESTful service that enables you to programmatically interact with the procurement platform. Use it to create and manage purchase requests, handle approvals, sync vendor data, and integrate with your existing ERP or financial systems.

📘 API Version

This documentation covers API v2.0. Version 1.0 is deprecated and will be sunset on December 31, 2025. Please migrate to v2.0 for continued support and new features.

Key Features

  • ✅ Full CRUD operations on purchase requests
  • ✅ Automated approval workflow triggers
  • ✅ Real-time webhook notifications
  • ✅ Bulk operations support
  • ✅ Comprehensive error handling
  • ✅ OAuth 2.0 and API key authentication

Authentication

All API requests require authentication using a Bearer token. You can generate API tokens from your ZipFlow dashboard under Settings → API Access. Tokens do not expire but can be revoked at any time.

Authorization: Bearer YOUR_API_TOKEN
// Include in all request headers

Obtaining an API Token

  1. Log in to your ZipFlow account
  2. Navigate to Settings → API Access
  3. Click "Generate New Token"
  4. Copy and securely store your token
⚠️ Security Notice

Never share your API token or commit it to version control. Treat it like a password. If compromised, revoke immediately and generate a new token.

Purchase Requests

GET /api/v2/requests

Retrieve a paginated list of purchase requests. Filter by status, date range, department, or vendor.

Query Parameters

Parameter Type Required Description
status string Optional Filter by status: pending, approved, rejected, cancelled
department_id integer Optional Filter by department ID
limit integer Optional Number of results per page (default: 20, max: 100)
offset integer Optional Number of results to skip for pagination
cURL 
curl -X GET "https://api.zipflow.com/v2/requests?status=pending&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
JavaScript 
const response = await fetch('https://api.zipflow.com/v2/requests?status=pending&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);
Python 
import requests

url = "https://api.zipflow.com/v2/requests"
params = {
    "status": "pending",
    "limit": 10
}
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

200 OK
JSON Response 
{
  "data": [
    {
      "id": 12345,
      "request_number": "REQ-2024-001",
      "status": "pending",
      "total_amount": 5420.50,
      "currency": "USD",
      "requester": {
        "id": 789,
        "name": "John Smith",
        "email": "john.smith@company.com"
      },
      "created_at": "2024-08-26T10:30:00Z",
      "updated_at": "2024-08-26T14:15:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}
POST /api/v2/requests

Create a new purchase request. The request will automatically enter the approval workflow based on your organization's rules.

Request Body

Field Type Required Description
vendor_id integer Required ID of the vendor
items array Required Array of line items
justification string Required Business justification for purchase
urgency string Optional low, normal, high, critical
cURL 
curl -X POST "https://api.zipflow.com/v2/requests" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": 456,
    "items": [
      {
        "description": "Office Supplies",
        "quantity": 10,
        "unit_price": 25.00
      }
    ],
    "justification": "Monthly office supplies replenishment",
    "urgency": "normal"
  }'
JavaScript 
const requestData = {
  vendor_id: 456,
  items: [
    {
      description: "Office Supplies",
      quantity: 10,
      unit_price: 25.00
    }
  ],
  justification: "Monthly office supplies replenishment",
  urgency: "normal"
};

const response = await fetch('https://api.zipflow.com/v2/requests', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestData)
});
Python 
import requests

url = "https://api.zipflow.com/v2/requests"
data = {
    "vendor_id": 456,
    "items": [
        {
            "description": "Office Supplies",
            "quantity": 10,
            "unit_price": 25.00
        }
    ],
    "justification": "Monthly office supplies replenishment",
    "urgency": "normal"
}

response = requests.post(url, json=data, headers=headers)

Response

201 Created
JSON Response 
{
  "id": 12346,
  "request_number": "REQ-2024-002",
  "status": "pending",
  "total_amount": 250.00,
  "approval_chain": [
    {
      "approver": "Manager",
      "status": "pending"
    }
  ],
  "created_at": "2024-08-28T15:30:00Z"
}
PUT /api/v2/requests/{id}

Update an existing purchase request. Only requests in "draft" or "returned" status can be modified.

DELETE /api/v2/requests/{id}

Cancel a purchase request. Only requests that haven't been fully approved can be cancelled.

Error Handling

The API uses standard HTTP status codes to indicate success or failure. All error responses include a JSON object with error details.

Status Code Description Common Causes
400 Bad Request Invalid parameters, malformed JSON
401 Unauthorized Missing or invalid API token
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side issue

Error Response Format

400 Bad Request
JSON Error Response 
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The vendor_id field is required",
    "field": "vendor_id",
    "request_id": "req_abc123"
  }
}

Rate Limiting

API requests are rate-limited to ensure platform stability. Rate limits are applied per API token.

Standard Limit

1,000 requests/hour

Burst Limit

50 requests/minute

Enterprise Limit

10,000 requests/hour
📘 Rate Limit Headers

Each response includes headers showing your current rate limit status:

  • X-RateLimit-Limit - Your rate limit
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Unix timestamp when limit resets

Webhooks

Configure webhooks to receive real-time notifications when events occur in ZipFlow. Webhooks are sent as HTTP POST requests to your specified endpoint.

Available Events

  • request.created - New purchase request created
  • request.approved - Request approved by all approvers
  • request.rejected - Request rejected by approver
  • request.cancelled - Request cancelled by requester
  • vendor.updated - Vendor information changed
Webhook Payload Example 
{
  "event": "request.approved",
  "timestamp": "2024-08-28T16:45:00Z",
  "data": {
    "request_id": 12345,
    "request_number": "REQ-2024-001",
    "total_amount": 5420.50,
    "approved_by": "jane.manager@company.com"
  }
}
← Back to Portfolio