Overview
The Plexus API lets your organisation connect Plexus to the other systems your business runs on, such as your CRM, finance or ERP platform, document storage, data warehouse or reporting tools. Instead of moving information between systems by hand, your developers can build integrations that read and update your Plexus documents automatically.
The API is designed for system-to-system integrations. Rather than signing in as a person, an integration signs in with its own dedicated identity, called a service account, and only sees and does what you allow it to.
The Plexus API is currently in Beta and is switched on per organisation. If you would like access, contact your Customer Success Manager.
Before you begin
To get started you will need:
The Plexus API enabled for your organisation. API access is off by default and is enabled on request during the Beta.
Your own account – either temporarily or permanently – assigned to a role with the Access account administration permission in order to view the API Access tab.
A new or existing role that has adequate permissions to view the documents you'd like access to as part of your integration. See 'Managing roles'.
A developer or IT team member who will build and maintain the integration.
Key concepts
There are two building blocks to understand before you connect an integration:
Service accounts
A service account is a non-human user that represents your integration inside Plexus. It belongs to an org unit and is given roles, just like a person would be, and those roles decide which documents it can see and what it can do with them.
Top tip! Name your service account carefully.
Every action is performed as the service account, and so anything your integration does is attributed to it in the document activity log, exactly as an in-product action would be. This keeps a clear audit trail of what was done by a person and what was done by an integration.
Service accounts are managed in the API access area. They are different to a standard user account as:
A person doesn't log into this account to use it;
They do not appear in your Settings > Users list;
They are not counted as people in your organisation; and
They do not count toward your user licences, regardless of the roles assigned.
Top tip! We recommend creating a separate service account for each integration, with only the access that integration needs.
Credentials
Credentials are the keys your integration uses to prove it is allowed to act as a service account. Each set of credentials is made up of a client ID and a client secret, and belongs to one service account. A service account can hold more than one credential, so you can switch an integration to a new credential before deleting the old one, without any downtime.
A few things to know about credentials:
The client secret is shown once. Copy it and store it somewhere secure, such as your organisation's secrets manager, as soon as it is created. Plexus cannot show it to you again.
You can rotate a secret at any time. Rotating generates a new secret and keeps the same client ID. The previous secret stops working immediately, so update your integration straight away.
You can revoke credentials when an integration is no longer needed or you suspect a secret has been exposed. Revoking stops access immediately.
Each organisation can hold a limited number of credentials. Contact Plexus if you need more.
Credentials do not carry their own permissions. What an integration can access is always controlled by the roles on its service account.
Plexus uses the OAuth 2.0 client credentials flow. Your integration exchanges its client ID and secret for an access token, then includes that token in each API call. Tokens expire, so reuse a token until it expires and then request a new one with the same credentials. The token endpoint and audience are shown on your credential under API Access.
For the full steps, examples and limits, see "Authentication" in the developer documentation.
Setting up API access
API access starts with a service account and a credential, which your integration uses to request access tokens and connect securely to Plexus. To set them up:
1. Navigate to Settings > Account
2. Click the tab for API Access – if you can't see this, reach out to the Plexus team.
3. Click + New service account.
4. Give it the name, roles and access it needs:
Account name: The name that will show in your audit trail for any API activity on applicable documents.
Organisation unit: Controls what documents the API has access to in the company structure. See 'Adding, Editing and Deleting Organisation Units' for a detailed summary.
Roles: Further enhances what the service account can see or do in Plexus. See 'Managing Roles' for more information.
5. Click Continue to credential to continue the setup.
Credential name: The name that will show in your audit trail for any API activity on applicable documents.
Description: Used for your own reference.
6. Click Create and show secret.
7. Copy the supplied details to a place where you will be able to access it later.
Top tip! For security, a client secret is only shown on this page once and cannot be retrieved later. If you leave or refresh this page without noting down these details, you'll need to rotate the credential from the list.
8. Open the API documentation at app.legalgateway.com.au/developers and sign in with your Plexus login. It lists every request the API supports, with examples.
9. Test your credential by sending a request from the documentation page before you connect your integration. Every request acts as your service account, so it only sees and changes what that account's roles allow. See 'Test the API from the documentation page' below.
10. Rotate or revoke credentials as part of your normal security practice.
Test the API from the documentation page
The API documentation has a built-in test console, so you can try requests against your own Plexus organisation before anyone writes code. Requests sent from the console are real: a document you create there appears in Plexus, so we recommend testing with a sample document.
Open the API documentation and sign in with your Plexus login.
In the left menu under API Reference, choose the request you want to try. To send a document into Plexus, choose Documents and facts > Create a document.
Click Test Request. A window opens with the request on the left and the response on the right.
Under Authentication, the Token URL is already filled in. Paste the Client ID and Client Secret from your credential, check the Audience matches the one shown on your credential, then click Authorise.
Under the Request Body, keep the example filters or adjust them, for example to a document type or counterparty you know.
Click Send. The response appears on the right. A 201 response means the document was created, and shows its id and key facts. If something is wrong, the response names each field that needs fixing.
Open Plexus to see your new document.
The same steps work for every other request in the documentation, such as finding documents or adding a comment. Open Code Snippet at the bottom of the request to copy it as code for your developers, or click Open API Client to try several requests in one place.
What you can do with the API
The API covers the core of working with documents in Plexus.
Find and read documents
Search and filter your documents using the same filters available in the document list, including status, counterparty, document type, contract value, owner and dates
Retrieve a document's details, including its key facts and additional key facts
View a document's version history, activity log, comments, workflow status, linked documents and supporting materials
Look up your organisation's document types and the fields available for filtering
Create and update documents
Create a new document with its key facts, and optionally set up reviewers, approvers and signers
Update a document's key facts and additional key facts
Upload a new version of a document, or the executed version
Add supporting materials and sub documents
Add comments and replies
Link and unlink related documents
Add and update signing locations
Full details of every endpoint, request and response are in the API documentation.
Example use cases
Here are some of the ways organisations use the Plexus API.
Create contracts from your CRM. When a deal reaches a set stage in your CRM, automatically create the contract in Plexus with the counterparty, contract value and owner already filled in, and route it to the right approvers.
Keep your finance or ERP system in sync. Pull executed contracts, contract values and start and expiry dates into your finance system so commitments and obligations are always up to date.
Bring signed contracts back into Plexus. If a contract is signed outside Plexus, upload the executed version through the API so your contract register stays complete.
Build reporting dashboards. Feed document status, values and dates into your data warehouse or BI tool to report on contract volumes, turnaround and upcoming renewals alongside the rest of your business data.
Stay ahead of renewals. Query documents by expiry date and trigger reminders or tasks in the tools your team already uses.
Support audits and compliance. Export a document's activity log and version history to your records or governance system as evidence of who did what and when.
Migrate or bulk load contracts. Move legacy contracts into Plexus with their key facts, so they are searchable and reportable from day one.
Security and limits
Least privilege. Integrations only see and do what their service account's roles allow. Minimise access to sensitive information across your organisation, or refresh your memory on our organisation structure and roles.
Clear attribution. Every change is recorded against the service account in the activity log. Creating, changing, rotating and revoking service accounts and credentials is also audited.
Rate limits. Requests are rate limited per organisation We monitor API usage and may get in touch if we notice unusually high request volumes, so we can help you get the most out of your integration.
Keep credentials safe. Never share credentials by email or chat, or commit it to source code. If you think a secret has been exposed, revoke or rotate it straight away.
API reference
The full API reference, including code samples and a try-it console, is available at app.legalgateway.com.au/developers. You will need to sign in to Plexus to view it.
Getting help
If you have questions about the Plexus API, or would like to join the Beta, contact your Customer Success Manager or reach out to our support team through the chat in Plexus.
Beta feedback is especially valuable to us. Let us know what works well, what is missing, and which integrations you would like to build next.
Need more assistance? Reach out to [email protected].