Evaluation

Technical overview

The Partner API is a server-to-server REST API over the records your customers already keep in Visena — people, companies, projects, activities and documents. One OAuth 2.0 credential, nine resources under one versioned contract, and writes that run through the same application services as Visena's own screens. This page is the architecture and the security model, for the people who have to sign the integration off.

One integration, the real Visena engine

Your systems create, read, update and delete the records that matter — people and companies, projects, activities, documents — inside a customer's Visena instance. There is no separate integration database and no nightly copy: a write lands on the same record a user would have edited, through the same application services, so validation and business rules behave as they do in the interface.

The practical consequence is that your integration inherits the platform's correctness rather than reimplementing it. A rule the interface enforces — a required field, a duplicate organisation number, a reference that must resolve — is enforced on your call too, and the failure comes back as a machine-readable problem document instead of a half-written record.

What the API gives you

A CRUD and synchronisation surface over the core CRM and work records, with the conventions an integrator expects. Everything below is available on the resources documented in the reference; the per-resource pages are the contract.

The three read modes, side by side

They are three different jobs, and picking the wrong one is the most common integration mistake we see. The list endpoints and their guarantees are covered in full under Lists, paging and sync.

# a page with a real total — for a screen or a picker
GET /acme/api/v1/en/person?offset=0&limit=50

# keyset paging — for a one-off extract, walked start to finish
GET /acme/api/v1/en/person/cursor?limit=100

# a time window — for ongoing synchronisation
GET /acme/api/v1/en/person/timeline?key=modified&since=2026-08-20T02:00:00Z

A surface that keeps growing

Nine resources are live today, all under one contract, one credential and one authentication scheme. The path carries an explicit version, so a resource added later is a new path under the same v1 — widening what your integration covers is new code against a familiar surface, not a re-integration.

Architecture at a glance

You talk to one public edge. It authenticates the call, resolves it to exactly one instance, and routes it to the engine. Everything behind that edge is internal to Visena and never something your integration addresses.

1. Authenticate. Exchange your client id and secret for an access token at /{instanceName}/auth/api/v1/token, using the OAuth 2.0 client-credentials grant.
2. Call. Send the token as an ordinary Authorization: Bearer header to any data endpoint. There is nothing else to sign.
3. The edge validates and isolates. The token is checked, and the instance named in the path has to be one the token is granted for. A call outside that grant is rejected at the edge, before it reaches any data.
4. The engine applies the same logic as the product. Writes go through Visena's own application services, so rules, validation and downstream effects fire as they would for a change made on screen.

Anatomy of a URL

Every call has the same shape: the instance, the API version, a locale, then the resource.

The locale decides the language of the messages that come back, not which records you see. The instance segment selects the customer, and it has to be one your token is granted for — a mismatch is refused at the edge rather than answered with someone else's data.

What your security team will want to know

The controls below are properties of the platform rather than options an integrator has to switch on. Credentials and tokens has the operational detail, and Read-only access walks through a credential that demonstrably cannot write.

• Opaque tokens. An access token is a reference value, not a container: there is nothing in it to decode, and it expires on its own — your backend renews it. A leaked token is a bounded window rather than a readable copy of anything.
• Secrets shown once. A credential secret is displayed a single time, at creation, and stored only as a one-way hash — it cannot be read back, by you or by Visena. A lost secret is replaced, never recovered.
• Per-instance isolation. A credential is granted to one instance, and the instance in the path has to match that grant — the edge resolves it, checks it, and refuses a mismatch. Behind that, each instance has its own database, so a request bound to one customer has no path to another's rows.
• Explicit scopes, and no permissive default. A token request has to name the scopes it wants: one that names none is refused with invalid_scope, not quietly granted everything. The read/write split is then enforced per request, in a filter ahead of the endpoint — which is why a credential issued for reading cannot write at all, rather than merely being expected not to.
• Masked identifiers. Records are addressed by masked ids, and the mask is derived per instance: the raw database key never crosses the wire in either direction, and the same record does not carry the same id in two different instances.
• Revocation. Revoke a credential and the tokens it minted stop working — expect the change to take effect within about a minute rather than instantly, because validation results are cached briefly. Offboarding a vendor is one call, not a wait for expiry.
• Attribution, never anonymous machine activity. A write through the API is attributed to a real person in the instance, in the same createdBy and modifiedBy fields the interface fills in — and where a call was made for someone else, actedBy names the actor as well. There is no unattributed API change.

How your team integrates

Three steps, and the first call is usually the same afternoon.

1. Get a credential. An administrator in the customer's Visena instance creates a partner credential for your integration and passes you the client id and secret securely. See Credentials and tokens.
2. Obtain a token. Your backend exchanges the credential for an access token at the token endpoint and refreshes it before it expires — a few lines in any HTTP stack. Getting started has it working end to end.
3. Build against the reference. Making requests covers headers, verbs and merge-patch, Errors and troubleshooting covers the failure modes, and the reference documents every endpoint, field and status per resource.

When you are ready for production, Going live is the checklist: scoped credentials, a rehearsed rotation, and what to monitor.

A foundation you can build a product on

The Partner API gives your team a standards-based path to data your customers already trust to Visena, with the platform's security model, instance isolation and business logic behind every call. There is no second data model to learn and no integrity gap between what your integration does and what the product does: the same services, the same rules, the same attribution.

Nine resources are live under one contract today, and the surface has grown by adding resources to it rather than by changing how you connect. That is the property worth designing against — the credential, the token exchange, the path shape and the error format you integrate once are the ones you keep.

Read getting started Browse the reference

Evaluating rather than building? Read-only access is the shortest proof of the security model — a credential that can read everything it is granted and write nothing at all.