ProWorkflow API v4

Build powerful integrations with ProWorkflow's Nexus project management platform.

Getting Started

The API lives at:

https://api.proworkflow.com/api/v4

You'll need an API key or JWT token to authenticate - check the Authentication section for details.

How Responses Work

Every response comes back as JSON. You'll always get a status field that tells you if things worked ("success") or not ("error").

The actual data you requested lives in the data field. For lists of things, you'll also get a meta object with counts and pagination info:

// Getting a list of companies
{
  "status": "success",
  "data": [...],      // Your companies
  "meta": {
    "count": 10,      // How many in this response
    "total": 250      // Total available
  }
}

// Getting a single project
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Website Redesign"
  }
}

// Something went wrong
{
  "status": "error",
  "data": [
    "What went wrong"
  ]
}

Making Requests

For GET and DELETE requests, just add parameters to the URL.

For POST and PUT requests, send JSON in the body with Content-Type: application/json.

What You Can Do

The API gives you access to everything in ProWorkflow:

• Companies & Contacts
• Projects & Tasks
• Time Tracking & Expenses
• Invoices & Quotes
• Custom Fields & Tags
• Reports & Settings

Most endpoints let you:

• Filter results with query parameters
• Choose which fields to return
• Page through large datasets
• Sort by different fields
• Create multiple items at once

Check out the endpoint documentation for specifics on what each one can do.

Authentication

There are a few ways to authenticate. Which one you use determines what permissions apply to your requests.

Authentication Methods

1. JWT Bearer Token (OAuth 2.0)

Pass a JWT in the Authorization header. This gives you user-level access — permissions, division scope, and sensitive field visibility all apply based on the user's settings.

JWTs are obtained via the OAuth 2.0 Authorization Code flow using the ProWorkflow identity server. Contact [email protected] to register an OAuth app and receive a client_id and client_secret.

Authorization URL:

https://identity.proworkflow.com/auth
  ?client_id=<client_id>
  &redirect_uri=<redirect_uri>
  &response_type=code
  &state=<random_state>
  &scope=openid email

After the user authorises, exchange the returned code for an access token at your token endpoint, then pass the token as a Bearer header on API requests.

2. API Key

Pass your API key as a header. This is account-level access — no permission restrictions, all sensitive fields visible, all divisions accessible. Best for integrations and automation.

Format: xxxx-xxxx-xxxx-xxxx-PWFxxxx (optional suffix: xxxx-xxxx-xxxx-xxxx-PWFxxxx-suffix)

API Key vs JWT

Setting Authentication

Try It Out

Use the Try it out panel in the sidebar to set your credentials, then use the Try It forms on any endpoint to make live requests.

Rate Limiting

The API enforces rate limiting to ensure fair usage and system stability.

Rate Limit

500 requests per 30-second window per API key or authenticated user.

• Rate limits are applied per API key for API key authentication
• Rate limits are applied per user for JWT authentication
• Each authentication method has its own independent rate limit

Response Headers

Every API response includes rate limit information in the headers:

Rate Limit Exceeded

When you exceed the rate limit, the API returns HTTP status 429 Too Many Requests. You must wait for the window to reset before making additional requests.

Best Practices

• Monitor the X-RateLimit-Remaining header to avoid hitting limits
• Implement exponential backoff when you receive 429 responses
• Cache responses when possible to reduce API calls
• Use field selection to minimize payload sizes
• Batch operations where supported

Record Limits

The API will return a maximum of 30,000 records. If your request exceeds this limit then only the first 30,000 records will be returned. We strongly suggest you design your application and requests such that you will not come close to this limit. For optimal performance you should plan your requests to return no more than 1,000 records and typically no more than 500.

If your usage of the API is impacting on response times for other customers then we reserve the right to limit or remove your access to the API (we would, of course, contact you first to try to avoid taking that step).

You can limit the number of items returning and improve performance by using the paging options and we encourage you to use these options to deliver a better experience to your users.

Pagination

Most collection endpoints are paginated. Pass pagenumber and pagesize to get a specific page. By default the total record count is not calculated — pass includetotalrows=true to include meta.total in the response.

Pagination Parameters

Default Behavior

• Without pagination parameters: Returns all matching records (up to endpoint limit)
• With pagination parameters: Returns specified page with metadata

Response Metadata

Paginated responses include a meta object with pagination details:

{
  "status": "success",
  "data": [...],
  "meta": {
    "count": 10,      // Items in this response
    "total": 250,     // Total matching records
    "page": 1,        // Current page number
    "pagesize": 10    // Items per page
  }
}

Total Count

The total field in the meta object reflects the true total count of all records matching your query filters, not just the items in the current page. This allows you to:

• Calculate the total number of pages: Math.ceil(total / pagesize)
• Show accurate progress indicators
• Know when you've retrieved all records

Opting in with includetotalrows

By default, the count query is not executed and total is omitted from the response meta. To include it, pass includetotalrows=true:

GET /api/v4/projects/items?pagenumber=1&pagesize=10&includetotalrows=true

{
  "status": "success",
  "data": [...],
  "meta": {
    "count": 10,
    "total": 13875,
    "page": 1,
    "pagesize": 10
  }
}

When includetotalrows is omitted or false, the total field is not returned and the count query is skipped, which can significantly improve response times on large datasets:

{
  "status": "success",
  "data": [...],
  "meta": {
    "count": 10,
    "page": 1,
    "pagesize": 10
  }
}

Sorting

Control the order of results with sorting parameters:

Common sort fields:

• id - Record ID
• name - Name field
• code - Code/identifier
• createdon - Creation date
• lastmodified - Last modification date
• sortorder - Custom drag-and-drop position (see below)

Custom Ordering

Some entities (projects, items, invoices, quotes) support drag-and-drop ordering via a dedicated endpoint. Use sortby=sortorder to return results in their custom order, and use the /order sub-endpoint to change position:

PUT /api/v4/{resource}/:id/order

Provide exactly one placement field in the request body:

Endpoints supporting custom ordering:

• PUT /api/v4/projects/:projectid/order
• PUT /api/v4/projects/items/:itemid/order
• PUT /api/v4/quotes/items/:itemid/order
• PUT /api/v4/invoices/items/:itemid/order
• PUT /api/v4/invoices/:invoiceid/order
• PUT /api/v4/quotes/:quoteid/order

Query Parameters Reference

A quick reference for the filtering and field selection parameters supported across GET endpoints. Parameters combine with AND logic unless noted.

Field Selection

Control which fields are returned in the response to optimize payload size.

Notes:

• The id field is always included automatically
• Invalid field names are silently ignored
• Field names are case-insensitive
• Default fields vary by endpoint when not specified

Search & Text Filtering

Search within text fields using these parameters:

Negation Search:

• Prefix search term with ! to exclude matches
• Example: ?search=!test returns items NOT containing "test"
• Works with field-specific searches too: ?searchname=!admin

Type & Status Filters

Filter by enumerated values like type, status, or state:

Common Values:

• Company types: client, contractor, staff, other
• Project status: active, complete, cancelled, archived
• Task status: pending, inprogress, complete

Date & Time Filters

Filter by dates using absolute or relative time:

Relative Time Units:

• n - minutes (e.g., 30n = 30 minutes)
• h - hours (e.g., 24h = 24 hours)
• d - days (e.g., 7d = 7 days)
• w - weeks (e.g., 4w = 4 weeks)
• m - months (e.g., 3m = 3 months)

UTC Variants: Some endpoints support UTC versions: lastmodifiedutcfrom, lastmodifiedutcto

ID Filters

Filter by specific IDs or ID ranges:

Relationship Filters

Filter by related entities:

Combining Parameters

This query finds:

• Client projects
• That are active OR pending
• Modified in the last 7 days
• NOT containing "test" in searchable fields
• Tagged with tag ID 1, 2, OR 3
• Returns only specified fields
• First 25 results
• Sorted by last modified date, newest first

Error Handling

All error responses have "status": "error" and a data array with one or more messages describing what went wrong.

HTTP Status Codes

Error Response Structure

All error responses follow this format:

{
  "status": "error",
  "data": [
    "Error message 1",
    "Error message 2"
  ]
}

The data array contains one or more descriptive error messages explaining what went wrong.

Permissions & Access Control

Access control works differently depending on how you authenticate. API keys bypass all permission checks. JWT tokens enforce the full user permission model.

Authentication Impact on Permissions

User Types

Every user has a type that determines their general access level:

Account Plans

Account plans determine available features:

Permission System

Permissions are identified by numeric IDs and control specific actions:

Permission Actions

Each permission supports different actions:

• view - Read access to resources
• add - Create new resources
• edit - Update existing resources
• delete - Delete resources

Sensitive Field Filtering

Users without ViewSensitiveBusinessInfo (Permission 11) have financial fields automatically hidden:

Affected Resources & Fields:

Division & Team Filtering

For Advanced plan accounts with multiple divisions:

Division Access:

• Users are assigned to a specific division
• Can only see/modify resources in their division
• divisionid parameter filters results
• Cross-division access requires special permissions

Team Access:

• Users can be part of teams within divisions
• ViewTeamWork (Permission 23) allows seeing team members' work
• Without team permission, users see only their own assigned work

Contact Filter Modes

The API uses contact filter modes to control work visibility:

Field Reference

The API provides flexible field selection to optimize response payloads. Use the fields parameter to control which fields are returned.

Field Selection

Important Notes:

• The id field is always included automatically
• Field names are case-insensitive
• Unknown field names are silently ignored
• Some fields require specific permissions to view

Common Field Types

Sensitive Financial Fields

Certain financial fields are restricted based on permissions. Users without ViewSensitiveBusinessInfo permission will not see these fields:

JSON Array Fields

Many resources include arrays of related objects:

Status Values by Entity

The status field represents different states for each entity type:

Computed vs Stored Fields

Stored Fields - Directly from database, support filtering/sorting:

• id, name, code, status, type
• createdon, lastmodified
• startdate, duedate

Computed Fields - Calculated at runtime, may not support filtering:

• percentcomplete - Calculated from task completion
• timeremaining - Based on estimates vs actuals
• profitmargin - Calculated from costs/revenue
• fullname - Concatenated from firstname + lastname
• age - Calculated from dates

Examples

Best Practices

1. Request only needed fields - Reduces payload size and improves performance
2. Check for field existence - Fields may be omitted based on permissions
3. Handle null values - Many fields can be null when not set
4. Parse arrays properly - Array fields may be empty arrays [] or omitted entirely
5. Respect field types - Don't assume string when API returns numbers

Batch Operations

Most POST endpoints accept either a single object or an array. Sending an array creates multiple records in one request.

Batch Creation Pattern

Single Item:

POST /api/v4/companies
{
  "name": "Acme Corp",
  "code": "ACM",
  "type": "client"
}

Array:

POST /api/v4/companies
[
  {
    "name": "Acme Corp",
    "code": "ACM",
    "type": "client"
  },
  {
    "name": "Beta Inc",
    "code": "BETA",
    "type": "contractor"
  }
]

Supported Endpoints

Most creation endpoints support batch operations:

• /companies - Create multiple companies
• /contacts - Create multiple contacts
• /projects - Create multiple projects
• /items - Create multiple items
• /timelogs - Create multiple time entries
• /expenses - Create multiple expenses
• /invoices - Create multiple invoices
• /quotes - Create multiple quotes

Response Format

Batch operations return a summary of the operation:

Partial Success Handling

If some items fail validation while others succeed, the API may:

1. Reject entire batch (default) - Returns error, no items created
2. Process valid items (some endpoints) - Creates valid items, reports errors

Check endpoint documentation for specific behavior.

Batch Update Pattern

Some endpoints support batch updates using filters:

PUT /api/v4/items/batch
{
  "filter": {
    "projectid": 123,
    "status": "pending"
  },
  "update": {
    "status": "inprogress",
    "assignedto": 456
  }
}

Examples

Batch Delete Operations

Some endpoints support batch deletion using ID lists:

DELETE /api/v4/items?ids=1,2,3,4,5

Or using filters:

DELETE /api/v4/items
{
  "filter": {
    "projectid": 123,
    "status": "cancelled"
  }
}

Data Types & Models

Field types and formats used across the API.

Nullable Fields

Many fields can be null, indicated by omission from the response when using omitempty:

{
  "id": 1,
  "name": "Project Alpha"
  // budget field omitted if null
}

Common Nullable Fields:

• Optional text fields (description, notes)
• Foreign keys (companyid, projectid when not required)
• Calculated fields (totals, percentages)
• Date fields (completeddate, duedate)

Date & Time Handling

Date Formats:

• ISO8601: 2024-01-18T13:20:00 (local time)
• ISO8601 with timezone: 2024-01-18T13:20:00Z (UTC)
• Date only: 2024-01-18

Relative Time (for filters):

• 12h - 12 hours ago
• 5d - 5 days ago
• 2w - 2 weeks ago
• 1m - 1 month ago

Enumerated Types

Many fields accept only specific values:

Company/Contact Types:

"type": "client" | "contractor" | "staff" | "other"

Project Status:

"status": "active" | "complete" | "cancelled" | "archived" | "pending"

Task Status:

"status": "pending" | "inprogress" | "complete" | "cancelled"

Priority Levels:

"priority": 1 | 2 | 3 | 4 | 5  // 1=Highest, 5=Lowest

Billing Types:

"billtype": 0 | 1 | 2 | 3
// 0=Non-billable, 1=Hourly, 2=Fixed, 3=Recurring

Money & Financial Fields

Financial values are represented as decimals with up to 2 decimal places:

{
  "budget": 50000.00,
  "spent": 12500.50,
  "remaining": 37499.50,
  "hourlyrate": 150.00
}

Important: Some financial fields may be hidden based on user permissions. See Permissions documentation.

Special Field Types

Color Fields:

"color": "4A90E2"  // 6-character hex color without #

Email Fields:

"email": "[email protected]"  // Validated email format

URL Fields:

"website": "https://example.com"  // Valid URL format

Composite Objects

Address Object:

"address": {
  "line1": "123 Main St",
  "line2": "Suite 100",
  "city": "New York",
  "state": "NY",
  "postalcode": "10001",
  "country": "USA"
}

Contact Name Object:

"contact": {
  "id": 123,
  "firstname": "John",
  "lastname": "Doe",
  "fullname": "John Doe",
  "email": "[email protected]"
}

Field Omission Rules

Fields are omitted from responses when:

1. They are null and marked with omitempty
2. User lacks permission to view them
3. They weren't requested via fields parameter
4. They are empty arrays or objects

Search & Filtering

This page covers the search and date range options. For the full parameter reference see Query Parameters.

Text Search

Search within text fields using various search parameters:

General Search

GET /api/v4/companies?search=acme

Searches across default searchable fields (usually name, code, description).

Field-Specific Search

GET /api/v4/contacts?searchname=john
GET /api/v4/[email protected]
GET /api/v4/companies?searchcode=ABC

Search within specific fields for more targeted results.

Negation Search

Prefix any search with ! to exclude matches:

GET /api/v4/projects?search=!test

Returns all projects that DON'T contain "test".

Filter Combinations

Filters work together to progressively narrow results:

Tag Filtering

Filter items by tags:

# Has ANY of these tags (OR logic)
GET /api/v4/projects?tagid=1,2,3

# Returns projects tagged with tag 1 OR 2 OR 3

Note: Currently no support for "has ALL tags" filtering.

Date Range Filtering

Filter by date ranges using absolute or relative dates:

Absolute Dates

GET /api/v4/projects?createdfrom=2024-01-01&createdto=2024-12-31
GET /api/v4/items?duefrom=2024-06-01&dueto=2024-06-30

Relative Time

# Items modified in last 24 hours
GET /api/v4/items?lastmodifiedfrom=24h

# Items created in last week
GET /api/v4/items?createdfrom=1w

# Items due in next 30 days
GET /api/v4/items?dueto=30d

Relative Time Units:

• n - minutes (30n = 30 minutes)
• h - hours (24h = 24 hours)
• d - days (7d = 7 days)
• w - weeks (2w = 2 weeks)
• m - months (3m = 3 months)

Nested Resource Filtering

Access filtered subsets via nested endpoints:

# Get contacts for a specific company
GET /api/v4/companies/123/contacts

# Get active projects for a company
GET /api/v4/companies/123/projects?status=active

# Get items assigned to a contact
GET /api/v4/contacts/456/items

Performance Tips

• Index-friendly filters (fast): id, status, type, companyid, projectid
• Full-text search (slower): search, searchname, searchdescription
• Combine with sorting: Add sortby and sortorder for consistent ordering
• Use specific searches: searchcode=ABC is faster than search=ABC