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 an OAuth access token to authenticate. See Authentication to choose between them.

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

Every request needs credentials. Pick the method that matches what you're building:

Setting up OAuth is self-serve: you don't need to contact Support.

How the two methods differ

OAuth (Bearer tokens)

OAuth lets an app act as a signed-in ProWorkflow user. A super user creates the account's OAuth client in Settings → Automation → OAuth Clients. Each account has one OAuth client.

• Connecting Claude? Follow Connect Claude. It takes a few minutes and needs no code.
• Building your own app? OAuth 2.0 covers the full authorization-code flow, token refresh and errors.

API key

Pass the key in the apikey header. Requests act at account level: no permission restrictions, all sensitive fields visible and all divisions accessible.

Format: xxxx-xxxx-xxxx-xxxx-PWFxxxx, optionally followed by a suffix (xxxx-xxxx-xxxx-xxxx-PWFxxxx-suffix).

If a request sends both an Authorization: Bearer header and an apikey header, the bearer token is used and the API key is ignored.

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.

Connect Claude

Connect Claude to ProWorkflow so it can find and update your projects, tasks, time, invoices, quotes and more from a chat. The connector works in Claude on the web, Claude Desktop and Claude mobile.

Each person signs in with their own ProWorkflow login, so Claude can only see and change what that person can in ProWorkflow.

You'll need:

• A ProWorkflow super user, to create the OAuth client. This is done once per account.
• The ProWorkflow MCP server URL: https://api.proworkflow.com/api/v4/mcp
• A ProWorkflow staff login for each person who connects. Client and contractor logins can't use the connector.

Step 1: Create the OAuth client in ProWorkflow

A super user does this once for the account.

1. In ProWorkflow, go to Settings → Automation → OAuth Clients.
2. Click Set up OAuth client.
3. Under Redirect URIs, keep the prefilled https://claude.ai/api/mcp/auth_callback.
4. Optionally add a Description, such as "Claude connector", then click Create client.
5. In the OAuth client created dialog, copy the Client ID and the Client Secret, then click Done.

Step 2: Add the connector in Claude

On a Free, Pro or Max plan, you add the connector to your own Claude account:

1. Go to Customize → Connectors and click Add custom connector.
2. Name it ProWorkflow and enter the server URL https://api.proworkflow.com/api/v4/mcp.
3. Enter the Client ID and Client Secret from step 1. Depending on your dialog, they're under Advanced settings, or you choose Use your own OAuth client when it asks how to sign in.
4. Click Add.

On a Team or Enterprise plan, an Owner adds the connector once for the organization:

1. Go to Organization settings → Connectors, click Add, then Custom. If Claude asks for the connector type, choose Web.
2. Enter the server URL, the Client ID and the Client Secret, then click Add.

Members then find ProWorkflow under Customize → Connectors, marked Custom.

Step 3: Connect and sign in

Each person connects with their own ProWorkflow login:

1. In Customize → Connectors, click Connect on ProWorkflow.
2. Sign in to ProWorkflow on the page that opens, with two-factor authentication if your account uses it.
3. The first time, approve access. Claude then confirms that ProWorkflow is connected.

In a chat, click +, then Connectors, and make sure ProWorkflow is turned on. Try asking: "List my active projects" or "Which of my tasks are due this week?"

What Claude can do

Claude can search, read, create, update and delete projects, tasks, phases, time records, time allocations, invoices and quotes (with their line items), requests, messages, project notes, companies and contacts. It can upload and download files, and reach any other part of the API, such as settings. See the MCP Server reference for every tool.

Everything follows the signed-in person's ProWorkflow role: the same permissions, division and sensitive-field visibility as in the app. To stop Claude using a tool, such as the delete tools, select ProWorkflow under Customize → Connectors and set that tool to Blocked.

Staying connected

Claude refreshes your sign-in in the background. If you haven't used the connector for about two weeks, or it has been a year since you signed in, Claude asks you to connect again.

To stop Claude's access:

• For one person: they disconnect ProWorkflow in Customize → Connectors.
• For everyone: delete the OAuth client in ProWorkflow (the trash icon). Sign-ins stop working right away. A request already signed in can keep working for up to 5 minutes, until its access token expires.

If you rotate the Client Secret, Claude keeps using the old one, and it stops working. Claude can't change a connector's OAuth details after it's added, so remove the connector and add it again with the new secret. Everyone then connects again.

Claude Code

Claude Code signs in through a page on your own computer instead of claude.ai, so it needs its own redirect URI:

1. Edit the OAuth client in ProWorkflow and add the redirect URI http://localhost:8080/callback. Any free port works, as long as you use the same one in the next step.
2. Add the server with the command shown here. It prompts for the Client Secret.
3. Run /mcp in Claude Code and choose ProWorkflow to sign in.

Troubleshooting

OAuth 2.0

Use OAuth when a ProWorkflow user signs in to your app and the app calls the API as them. Their access token carries their permissions, division and sensitive-field visibility, exactly as in the ProWorkflow app.

Only staff users can use the API through OAuth. If a client or contractor signs in, the API rejects their token with 401.

Connecting Claude rather than building an app? Follow Connect Claude instead.

At a glance

1. Create an OAuth client

A super user creates the client in ProWorkflow. You don't need to contact Support.

1. Go to Settings → Automation → OAuth Clients.
2. Click Set up OAuth client.
3. Under Redirect URIs, replace the prefilled Claude URI with your app's callback, such as https://yourapp.com/oauth/callback. Click Add redirect URI for others, such as http://localhost:3000/oauth/callback for development.
4. Optionally add a Description, then click Create client.
5. In the OAuth client created dialog, copy the Client ID and Client Secret, then click Done.

Each account can have one OAuth client. Several apps, such as your own app and a Claude connector, can share it: add each app's callback to its redirect URIs.

2. Send the user to sign in

Redirect the user's browser to the authorize URL (example on the right):

The user signs in to ProWorkflow and, the first time, approves your app. The browser then returns to redirect_uri?code=...&state=.... Check that state matches the value you stored.

3. Exchange the code for tokens

Within 1 minute, POST the code to the token URL as application/x-www-form-urlencoded, with grant_type=authorization_code, the code, the same redirect_uri, your client_id and client_secret, and the code_verifier if you sent a PKCE challenge.

The response contains an access_token, which lasts 5 minutes, a refresh_token and an id_token.

4. Call the API

Send the access token on every request:

Authorization: Bearer <access_token>

5. Refresh the access token

Access tokens last 5 minutes. Refresh shortly before expires_in runs out, or when the API returns 401, by posting grant_type=refresh_token with the refresh token and your client credentials.

The response can include a new refresh_token. Always store the one you get back: once it's replaced, the old one stops working. A refresh token lasts 14 days. Refreshing in the second half of that period returns a new one with a fresh 14 days. An app that refreshes regularly keeps the user signed in for up to a year. After that, or after 14 days without a refresh, the user signs in again.

Manage your client

Your client is listed under Settings → Automation → OAuth Clients, with icons for each action:

• Edit (pencil): change its redirect URIs and description.
• Rotate secret: issue a new Client Secret. The old secret stops working immediately, so update every app that uses it.
• Delete (trash): sign-ins and token refreshes stop working immediately. Access tokens already issued keep working until they expire, within 5 minutes. A new client gets a new Client ID and Client Secret, so reconfigure your apps.

Common errors

Token URL errors are JSON in the standard OAuth form: {"error": "invalid_grant", "error_description": "..."}.

Security checklist

• Keep client_secret on your server. Never ship it in a browser or mobile app.
• Always check state, and use PKCE.
• Use HTTPS for every production redirect URI.
• Store refresh tokens encrypted. Rotate the client secret if it may have leaked.

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 per IP address for OAuth (bearer token) requests.

• API key requests are limited per API key
• OAuth requests are limited per IP address, so users of an app behind one IP share its 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

Several endpoints change many records in one request. They take the IDs of the records in the body.

Bulk updates

PUT on a collection applies the same changes to every record in ids. Only the fields you send change.

Bulk date shifts

PUT /projects/adjustdates moves projects' start and due dates by shiftdates days (negative moves them earlier), and their items' dates by shiftchilddates. PUT /projects/phases/adjustdates, /invoices/phases/adjustdates and /quotes/phases/adjustdates do the same for phases.

Bulk deletes

DELETE on a collection deletes every record in ids: DELETE /projects, /invoices, /quotes, /timeallocations and /files.

Many records at once

These add or remove a relationship on several records: id lists the records and the other array the values.

Creating several records

Create endpoints take one record per request: send an array and they answer 400 Invalid request body. Send one request per record.

Time allocations are the exception. POST /timeallocations takes an array and creates them all, and PUT /timeallocations updates several, each with its id.

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