API access - use Proyex programmatically

Written By Miro Flemke

Last updated 3 months ago

What is API access?

The Proyex REST API allows you to programmatically read and edit Proyex data. Use the API for your own integrations, automations, or to connect Proyex with your existing tools.

API access is available starting with the Professional plan.

Authentication

Personal API Token

  1. Go to Profile > API.

  2. Click Create Token.

  3. Give the token a name (e.g., "My Integration").

  4. The token is displayed only once—copy it immediately, as it cannot be viewed again.

Use the token as a bearer token in your API requests:

Authorization: Bearer dein-token

Revoke token

You can revoke individual tokens at any time. The token becomes invalid immediately and cannot be restored.

Available endpoints

The API provides access to all key areas of Proyex:

Projects

List, create, edit, delete

Tasks

CRUD, change status, assign, filter

Subtasks

Create, edit, delete

Milestones

List, create, edit

Time entries

Start/stop timer, create manually, statistics

CRM

Deals, contacts, companies, activities, pipelines

Custom fields

Manage fields and values

Files

Upload, list, delete

Notes

Create, edit, delete

Chat

Conversations and messages

Notifications

List, mark as read

Webhooks

Subscribe and manage

Revisions

List and version history

API format

All requests and responses use JSON. Base URL:

https://app.proyex.io/api/v1/

Successful response

For successful requests, you receive a JSON object containing the requested data and a success message.

Error

In case of errors, you will receive a status code (e.g., 400, 403, 404, 422) with an error description.

Filtering, sorting and aggregating lists

List endpoints like GET /api/v1/deals support powerful filter and sort options that let you reduce large datasets server-side — perfect for reporting and bulk reads.

Filtering

You can filter by status, date, UTM parameters or your own custom fields. Examples for /api/v1/deals:

  • ?status=won — only won deals (also open, lost, archived, all)

  • ?closed_at_from=2026-01-01&closed_at_to=2026-03-31 — filter on the close date

  • ?utm_source=ig&utm_campaign=spring-2026 — filter on UTM columns (also utm_medium, utm_term, utm_content)

  • ?custom_fields[offer_value][gte]=5000 — filter on custom field values (operators: eq, gte, lte, contains)

Important (Breaking Change): Without a ?status parameter, archived deals are hidden by default. Set ?status=archived or ?status=all to see them again.

Sorting

Use ?sort=field for ascending or ?sort=-field for descending. The default is -updated_at (newest first). NULL values (e.g. closed_at on open deals) automatically land at the end, regardless of direction.

Loading relations (?include=)

Instead of multiple follow-up requests, load relations directly. Comma-separated, whitelisted:

  • contact, owner, projects, activities, custom_fields, creator

  • contact_attribution — the UTM values of the linked contact as first-touch, in addition to the UTM values on the deal itself (last-touch)

Unknown include values are rejected with status 422.

Pagination keeps filters

The pagination links in meta.links[].url contain all active filter and sort parameters. You can follow pagination links directly without reconstructing query parameters.

Aggregates / Reporting

For reports without downloading entire datasets, use GET /api/v1/deals/stats:

/api/v1/deals/stats?group_by=utm_source&since=2026-01-01&until=2026-03-31&status=won

Returns count, sum_value and avg_value per group. You can group by utm_source, utm_medium, utm_campaign, stage_id, owner_id or pipeline_id.

Paginated activities

On the deal detail we ship the 20 latest activities directly. For the full list, use the sub-endpoint: GET /api/v1/deals/{id}/activities (paginated, default 20, max 100 per page).

Filtering lists by date

On the CRM list endpoints — deals, contacts, companies, activities and leads — you can now filter results by creation and update date in addition to sorting.

Optional query parameters (dates in ISO format, e.g. 2026-01-31): created_after, created_before, updated_after, updated_before.

Example:

GET /api/v1/deals?teamId=1&updated_after=2026-01-01

You can combine the parameters. An invalid date returns status 422.

Rate Limiting

The API is limited to a certain number of requests per minute. If you exceed the limit, you will receive an error message (status 429). Please wait a moment and try again.

Permissions

API tokens have the same permissions as the user who created them. You can only access data that you can also access via the web interface.

Frequently Asked Questions

Can I create multiple tokens?

Yes, you can create as many tokens as you like—for example, one per integration or per service.

What happens if I lose my token?

You can revoke the old token and create a new one. The lost token will no longer work after that.

Is there API documentation?

Yes, the API is fully documented. You can find the documentation under your Proyex URL in the API section.

Tips & Notes

  • Create separate tokens for each integration—this way, you can revoke individual connections without affecting others.

  • Use the API in combination with webhooks for powerful two-way integrations.

  • Be mindful of rate limiting for automated requests and build in wait times.