Help Center

How can we help?

Step-by-step answers for PVology, written for what you are trying to do.

PVology Connect

Ask PVology about your integrationsAsk PVology answers questions such as "Which integrations need attention?", "Why did this sync fail?" or "Which credentials expire this month?" from PVology Connect's facts (health, jobs, failures, expiry dates), within your Connect rights, without secrets.
Automatic retries and writes PVology could not confirmWhen the other system cannot be reached, times out, limits requests or answers a server error, PVology retries automatically after about 1 minute, 5 minutes, 30 minutes and 2 hours (with a small random spread), at most 4 times. Validation and permission errors are not retried. When an answer to a write is lost, PVology checks first and never repeats the write blindly.
Browse the connector catalog: Available, Beta, Coming soon and PlannedConnect → Catalog lists every connector with its status, authentication, objects, directions, requirements and limitations. Only Available and Beta connectors work; Coming soon, Needs your account and Planned ones are never functional, and no vendor partnership or certification is implied.
Connect reports and operational exportsConnect → Reports creates formal reports about your integrations with PVology's report service (PDF, Word or Excel, with a snapshot) and points to the operational exports of logs, failed records and jobs. Reports show names, states, counts, dates and codes, never credentials, payloads or record values.
Connect your own system's REST API (Generic REST connection, Beta)The Generic REST connection lets PVology read from (and, when set up, send back to) your organization's own system through its REST API, with your own credential: create the connection with your API's HTTPS address, save the credential, test, say where each kind of record is, map, dry-run and activate.
Developer guide: API authenticationSend Authorization: Bearer <credential> on every request. An API client can use an API key directly, or its client ID and secret with the OAuth 2.0 client-credentials grant at POST /api/v1/oauth/token (client_secret_basic or client_secret_post) for a 15-minute access token. Keys created before PVology Connect keep working.
Developer guide: API error handlingEvery error is one JSON body with RFC 9457 member names (type, title, status, detail, code, correlationId, retryable, errors[] per field) and, for v1 clients, error: { code, message, correlationId }. Decide on code and retryable; quote correlationId to PVology Support. Errors never contain stack traces, SQL or secrets.
Developer guide: API versioning and deprecationThe version is in the path (/api/v1) and in the pvology-api-version answer header. Within v1 only additions are made (new endpoints, fields, optional parameters): ignore fields you do not know. A breaking change would come as /api/v2 with at least 12 months of overlap, Deprecation and Sunset headers, a changelog entry and a migration guide.
Developer guide: authorization and scopesEvery request passes one authorization chain: credential, client, workspace, organization policy, allowed addresses, environment, scope, owner (for writes) and the application's entitlement, then the application's own access rules for each record. Scopes are explicit, none is granted by default and none implies another.
Developer guide: building a custom integrationTo integrate a system that has no connector: let PVology pull from its REST API with the Generic REST connection (Beta), push from it with an API client and idempotent POSTs, notify it with webhooks, or exchange files. Start in the sandbox, decide the source of truth, map and dry-run, then go live and watch health.
Developer guide: conflict handlingA conflict is a mapped field changed on both sides since the last sync (three-way comparison with stored per-field hashes). The policy of the mapping decides: PVology wins, the other system wins, review by a person, or skip. A record in conflict is never half-written; recommendations are never applied by themselves.
Developer guide: data mappingA mapping turns a source record into a PVology record of one contract object (for example projects.project or strategy.actual): field to field with a fixed list of typed transformations, defaults, validation and identity rules (external ID, then dedupe keys). Mappings are versioned (draft, validated, active, superseded) and activated only after a test and a dry run.
Developer guide: data synchronizationA sync reads the other system, captures its field schema, compares each record field by field with PVology using stored fingerprints and writes only through the application's services, in bounded slices. Transient failures are retried with back-off and jitter; permanent ones become failed records; lost answers are verified before anything is sent again.
Developer guide: how PVology Connect is builtPVology Connect is one shared integration foundation for every application: connectors (reusable definitions) and connections (one workspace's configured instance), one mapping and import engine, one sync engine, one API, one event catalog. Applications declare contracts and keep every write in their own services, with their permissions, rules and history.
Developer guide: idempotent requestsEvery POST needs an Idempotency-Key header (16 to 80 letters, digits, - or _), one per intended action. The same key with the same body returns the same answer (idempotency-replayed: true); the same key with another body is refused with 422 idempotency_key_reused. Writes are also recognised by externalId next time, so a retry never duplicates a record.
Developer guide: pagination, filtering and field selectionLists answer { data, nextCursor }. Ask for 1 to 200 records with ?limit= (100 by default) and pass ?cursor=<nextCursor> for the next page. Filters are listed per endpoint (for example status and updatedSince); ?fields= selects only the fields you need from those the endpoint may return.
Developer guide: rate limits and quotasStandard allowance per API client: 120 requests a minute and 10,000 a day; Limited: 10 a minute and 1,000 a day; keys created before PVology Connect: 60 a minute; a workspace ceiling of 600 a minute. Every answer carries RateLimit, RateLimit-Policy and RateLimit-Limit/-Remaining/-Reset headers; over the limit the answer is 429 with Retry-After.
Developer guide: receiving PVology webhooksPVology sends each subscribed event as an HTTPS POST with a JSON body and the headers PVology-Signature, PVology-Event, PVology-Delivery, PVology-Event-Id, PVology-Event-Version and PVology-Request-Id. Answer 2xx quickly; failures are retried after 1 minute, 5 minutes, 30 minutes and 2 hours, and failed deliveries can be replayed with the same event id.
Developer guide: SCIM 2.0 integrationPVology's SCIM endpoints (/api/scim/v2/Users, /Groups, /ServiceProviderConfig, /ResourceTypes, /Schemas) follow the SCIM 2.0 protocol for the parts identity providers use: filters with and, or, not and parentheses, paging, and PATCH. A SCIM token selects the organization; provisioning answers only after PVology switches it on for that organization.
Developer guide: secure credential managementPVology encrypts connection credentials and keeps only fingerprints of API keys, client secrets, access tokens and SCIM tokens. Every secret is shown once, never in logs, URLs, e-mails, AI facts or the Control Center. Use one credential per tool, the least access needed, an expiry, and rotation with overlap.
Developer guide: single sign-on architecturePVology is an OpenID Connect client: authorization code with PKCE (S256), state and nonce, discovery checks, ID tokens signed with RS256, PS256 or ES256, exact issuer, audience and authorized party checks, and time checks with a 2-minute allowance. Test sign-in shows the claims without creating a session; member sign-in is switched on per organization after a joint test.
Developer guide: source of truthEach connection and mapping has an explicit source-of-truth mode: PVology authoritative, external authoritative, PVology reads external, PVology publishes external, controlled two-way (one owner per field) or reference only. Fields owned by another system are read-only in PVology and refused through the API with field_managed_externally.
Developer guide: the PVology API at a glanceThe PVology API (/api/v1) reads and sends data for every PVology application with an API client's credential: JSON over HTTPS, cursor paging, scopes you choose, rate limits with headers, one error model, idempotent writes that go through each application's own rules, and an OpenAPI 3.1 description at /api/v1/openapi.json.
Developer guide: the PVology event modelPVology events are business facts such as crm.deal_won, projects.milestone_overdue, performance.actual.approved, governance.risk.created or connect.sync.completed. Each external event has integer versions, each with a fixed list of facts and a JSON Schema. GET /api/v1/events returns the catalog; endpoints pin a version per event.
Developer guide: webhook security and signature checksPVology-Signature is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your signing secret>. Recompute it, compare in constant time, accept any v1 value (there are two during a secret rotation) and reject timestamps older than 5 minutes. Incoming webhooks to PVology use the same scheme.
Enterprise identity in PVology: what is ready and what is switched onConnect → Identity prepares single sign-on (OpenID Connect), verified domains and SCIM provisioning for an organization. They are built and tested and stay Off until PVology switches them on for your organization after a joint test with your identity provider. Owners always keep password sign-in.
Events and event versionsConnect → Events lists every event PVology can send, with its application, record and versions, and the facts each version carries. Each webhook endpoint pins every event to a version, so a new version never changes what your receiver gets until you choose it.
External references: how PVology prevents duplicate recordsEvery record that comes in keeps the other system's ID as an external reference. The next import or sync finds it by that reference first, then by the mapping's ID field or dedupe keys (such as a project code, web domain or e-mail). A name alone never matches, and an ambiguous match waits for a person.
How SCIM provisioning works and how to prepare itUnder Connect → Identity → SCIM provisioning, create a SCIM token (shown once) and map your identity provider's groups to PVology roles. Once PVology switches provisioning on after a joint test, your provider adds people to the organization, updates them and deactivates them. Deactivating never deletes a person, their records or the audit trail.
How to activate a connectionWhen the last test of the current settings and credential passed, choose Activate connection on the connection. Activating moves no record by itself: records move only when you apply a dry run of an active mapping or run a sync.
How to add, rotate or revoke a connection credentialOpen the connection and, under Credential, enter the secret (with an optional expiry date) and choose Save credential, or Rotate credential to replace it; Revoke credential stops it at once. Then choose Test connection again. Only owners and administrators can do this.
How to choose API permissions (scopes)Each API client has only the permissions you choose, from 14 scopes such as Read projects, Update the project register, Send measure actuals, Send evidence for review or Run import jobs. No scope is granted by default and none implies another. Change them on the client with Change permissions.
How to configure single sign-on (SSO)Connect → Identity → Single sign-on configuration: enter your OpenID Connect provider's issuer, client ID and client secret, choose the verified domains and choose Save configuration, then Test sign-in. PVology shows the claims it received without creating a session. PVology switches SSO on after a joint test.
How to create a connectionConnect → Connections → New connection: choose the connector, a name, the environment, the direction and the source of truth, and choose Create connection. The connection opens in Draft; nothing is contacted until it is tested.
How to create an outgoing webhookConnect → Webhooks → Add an endpoint: enter the HTTPS address of your receiver, choose the events (each at its current version) and the payload format, and choose Add endpoint. Copy the signing secret from the Shown once box and verify every request's signature.
How to disable or enable a connectionChoose Disable connection on the connection to switch it off: nothing runs until you choose Enable connection. Nothing is deleted and the credential is kept.
How to disconnect a system, and what happens to imported dataOpen the connection and choose Disconnect…: PVology lists exactly what happens, then Disconnect stops its schedules and webhooks and revokes its credential. Imported records stay in their applications, and external references, jobs, logs and the audit trail are kept. Nothing is deleted.
How to export data in a structured fileConnect → Imports & exports → Exports downloads records as CSV or Excel, with only the records and fields you may see. Money fields need finance access, and cells a spreadsheet could run as a formula are neutralized in every PVology export.
How to get API access: create an API clientConnect → API access → Create an API client: name it after the tool, choose only the permissions (scopes) it needs (nothing is granted by default), set allowed addresses and expiry and choose Create API client. Copy the credential from the Shown once box into the tool.
How to import a CSV, Excel or JSON fileConnect → Imports & exports → New import: choose what the file contains, upload it, map its columns, run a dry run and choose Apply import. Records are recognised by the other system's ID, so importing again never duplicates them.
How to let another system create records in PVology (incoming webhooks)Connect → Webhooks → Incoming webhooks: choose what it does (for example create a Dealflow lead or add an action to a project) and Create incoming webhook. Copy the private address and signing secret (shown once). Every request must be signed; a repeated event id has one effect.
How to map fields (and update a mapping later)Open the connection and, under Mappings, choose Configure mapping. Read the source fields, map each one to a PVology field with a transformation, default and validation, test the mapping on up to 20 records, run a dry run and activate the version. Changing it later saves a new version; the active one keeps working until you activate the new one.
How to preview an import before anything changesEvery import has a preview: after mapping the columns, choose Run dry run. The preview lists what would be created, updated, left unchanged, skipped or refused, with the reason for each record. Nothing is imported until you choose Apply import.
How to resend (replay) a failed webhookIn Connect → Webhooks → Delivery log, choose Send again on the delivery. PVology sends a new delivery with the same event id, so your receiver can recognise it as the same event; the replay is audited.
How to resolve a sync conflictA conflict means the same field changed in PVology and in the other system since the last sync. Nothing was overwritten: open Connect → Sync → Conflicts, compare both values and choose Keep PVology's value, Use the other system's value, or decide another value, then Resolve this conflict.
How to retry, skip or resolve failed recordsConnect → Sync → Failed records lists every record that did not go in, with the reason. Fix the cause, then choose Retry selected (or Retry this record); choose Skip it with a reason, or Mark resolved when it was fixed by hand. Records are never dropped silently.
How to revoke API access or rotate an API client's credentialOpen the client in Connect → API access. Rotate credential issues a new one (the old one stays valid for 24 hours or stops now, your choice); Revoke client refuses every key, secret and token of the client from the next request. History, usage and audit are kept.
How to rotate a webhook signing secretOn the endpoint choose Rotate secret. Keep the previous secret signing for 24 hours (recommended) so your receiver can switch without missing events, or stop the previous secret now if it may have been seen by someone else. The new secret is shown once.
How to run a dry runA dry run processes every record exactly as a real import or sync would and writes nothing: it shows what would be created, updated, left unchanged, skipped, in conflict or refused, with the reason for each record. Choose Run dry run on the mapping or the import.
How to set up a two-way sync safelyTwo-way is never the default. Set the connection's direction to Both ways (controlled) and its source of truth to Controlled two-way, then give every mapped field one owner, PVology or the other system. PVology sends back only the fields it owns and never re-sends a change that came from the same connection.
How to start a manual sync or choose a scheduleOpen the connection and, under Sync, choose Run sync for a kind of record (it needs an active mapping). To sync regularly, choose a schedule (manual, hourly, daily or weekly) and Save schedule.
How to test a connectionOpen the connection and choose Test connection. It checks reachability, authentication, the required permissions and a basic capability, and shows each check as Passed, Failed or Not checked. No business data is read into PVology or changed anywhere.
How to test a field mappingOn the mapping choose Save and test mapping: PVology applies the mapping to up to 20 records from the source and shows each record's result with any error per field. Nothing is written.
How to test a webhookOn the endpoint choose Send a test event: PVology sends a sample event labelled TEST, with no customer data, now. No record changes and test events are not retried.
How to verify your organization's domainConnect → Identity: enter the domain and choose Add domain, add the DNS TXT record PVology shows at your DNS provider, then choose Check. A verified domain only allows people from that domain to use your single sign-on; it never adds members, roles or rights.
Is PVology Connect included in my plan?Yes. PVology Connect is included wherever your workspace is, with no separate price, plan or licence: everything that was available as Integrations stays available on the same plans, and the Connect foundation (connections, mappings, imports and exports, sync, API clients, webhooks with versions, the sandbox) came with it.
PVology Connect: what it is and where to find itPVology Connect (Integrations & Enterprise Connectivity) connects PVology to the systems your organization already uses: connections with tested credentials, mappings, imports and exports, sync, webhooks, the PVology API and enterprise identity readiness. Open the menu, choose Insights & tools, then Connect.
Read Connect logs and how long they are keptConnect → Logs shows what PVology Connect did, with a reference for each operation: filter by time, connection, level, code or reference and open an entry for details. Logs are kept 90 days by default; owners and administrators can choose between 30 and 365 days in Settings.
Review webhook deliveries (and why a webhook failed)Connect → Webhooks → Delivery log lists every delivery with its event, status, attempts and answer. Open Details for each attempt's time, answer code, answer time and error. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes and 2 hours.
Source of truth: which system owns each record and fieldEvery connection says which side is the source of truth: PVology authoritative, the other system authoritative, PVology reads the other system, PVology publishes to it, controlled two-way (one owner per field) or reference only. A connection never changes which application owns a record unless it is explicitly set up to be authoritative.
Transformations and how dates stay on the right dayTransformations are a fixed, typed list: trim, upper, lower or title case, date parsing with an explicit format and time zone, booleans, value lists, unit conversion, join and split, multiply or divide by a constant, lookups and defaults. No scripts. Dates without a time are kept as calendar dates, so time zones never move a due date.
Troubleshoot a schema change (the other system's fields changed)When a mapped field is removed, renamed or changes type in the other system, the sync stops before writing and the connection shows Schema changed: syncs are paused. Read the fields again on the mapping, fix it, test it, dry-run and activate the new version.
Try PVology Connect safely with the North River sandboxConnect → Sandbox → Add the North River sandbox adds a tested sample connection (dry runs only), a simulated signed webhook delivery, a sample API client and, in an organization, a mock identity provider with fictional people. Everything is marked SAMPLE and runs inside PVology with no network.
Understand connection health and its reasonsA connection's health is Healthy, Degraded, Action required, Error, Off or Not running yet, worked out from what happened (credential, tests, recent errors, owner, policy, sync results), never from a score. Each reason says what to do.
Understand sync resultsA job shows how many records were read, created, updated, unchanged, skipped, in conflict and failed, and lists every record with its outcome and reason. Its status is worked out from the counts: Success, Success with warnings, Partial, Requires review, Retrying, Failed. A sync is never shown as completed when records failed.
Use PVology AI safely in PVology ConnectPVology AI drafts mapping suggestions, explains what happened in a job or a conflict, summarizes logs and suggests setup steps. Suggestions are drafts a person applies; PVology AI never sees or shows credentials and never activates, approves, retries or replays anything.
Who can do what in PVology Connect (the Integration Administrator role)Owners and administrators can do everything. The Integration Administrator role manages connections, mappings, sync, imports, webhooks, API access and logs, but never credentials or identity. Owners and administrators give the role in Organization → Members.
Why a field says "Managed by" another systemWhen a connection is the source of truth for some fields, those fields show Managed by <connection name> on the record and cannot be edited in PVology (also not through the API or an incoming webhook). Change the value in the other system; the next sync brings it in.
Why am I rate limited? (HTTP 429)Each API client may send 120 requests a minute and 10,000 a day (Standard allowance); keys created before PVology Connect keep 60 a minute, and a workspace has a ceiling of 600 a minute. Over the limit, the API answers 429 with Retry-After: wait that long, then send again.
Why can't I access PVology Connect or an integration?PVology Connect has no separate plan or licence. In an organization you need the owner, administrator or Integration Administrator role to manage integrations; credentials and identity need an owner or administrator; and your organization's policies can switch a kind of integration off. "Why can't I?" next to a button gives the reason.
Why can't I see the credential?By design nobody can read a saved credential back: not you, not an administrator and not PVology staff. PVology keeps it encrypted and shows only its status, a short hint and the expiry date. If you need it, rotate it in the other system and save the new one.
Why did this integration (or sync) fail?Open the job (Connect → Sync) or the connection and read Why did this happen?: the reason code and a plain explanation, for example the credential was rejected, the other system could not be reached or limited requests (retried automatically), its fields changed, or records were refused by validation. Each reason gives the next step.
Why is SSO not working? Troubleshoot sign-in and authenticationSingle sign-on is prepared and tested in Connect → Identity but members cannot use it until PVology switches it on for your organization after a joint test; until then everyone signs in with their PVology account. For a failing Test sign-in, check the issuer, client ID, secret, redirect address and verified domains.

Still need help?

PVology Support creates a request for you at once, answers ordinary questions straight away and brings in a specialist when needed.

Contact PVology →