Overview
CX Platform exposes a set of RESTful APIs that let your business systems — your CRM, ERP, customer portal, mobile app, or anything else — talk directly to the platform. That means you can send documents, search the Archive, and retrieve previously sent communications without anyone needing to log in to CX Platform manually.
The APIs use standard JSON requests and responses, with HTTPS handling channel security and message integrity. If your developers have worked with RESTful APIs before, they'll feel right at home.
This guide is a high-level introduction. It covers the main Archive endpoints, how authentication is structured, and the security approaches you can use when surfacing documents to your end users. Detailed technical reference material lives separately for your development team.
How authentication works
Every request to the CX Platform API is authenticated using an API key. There are two layers to be aware of, and they work together.
Tenant API key
This is your top-level key — it identifies the calling system and grants access to the API. Each tenant can have multiple keys, one for each system that needs to integrate. So you might have one key for your website, another for your CRM, and a separate one for your ERP. Each key is IP whitelisted independently, and Test and Production environments use different keys.
Application API key
On top of the tenant key, sending a document through CX Platform also requires an Application API key. This identifies the specific document type you're sending — your welcome letter, monthly statement, or invoice, for example. Having a separate key per Application means there's no chance of accidentally sending the wrong document type when promoting code from Test to Production.
Good to know
API keys should only ever live on your server. Never embed them in front-end code like JavaScript or mobile apps, where they could be exposed.
Archive API endpoints
The Archive endpoints are where you'll spend most of your time when retrieving previously sent communications. They let you search, view content, and pull down attachments — useful for building things like a "your statements" page in a customer portal, or a document viewer inside your CRM.
Here's a quick rundown of the three endpoints you'll work with:
Keeping document access secure
If you're presenting Archive search results to end users — say, a list of statements inside your internet banking site — there's an important security consideration to think through. Without the right safeguards, a determined user could tamper with the request and try to access documents that aren't theirs.
CX Platform supports several approaches to prevent this, and the right one depends on who's using your system and how it's set up.
HMAC signatures
The simplest option for most customer-facing scenarios. When CX Platform returns search results, each document includes a unique signature that's tied specifically to that document. When the document is later requested, the platform verifies the signature matches. If it doesn't, the request is rejected. This means even if someone tries to modify the request to access a different document, they won't get through — and you don't need to build any extra checks on your side.
Trusted users
If your integration is only used by trusted internal staff — for example, document retrieval inside an ERP or CRM where users already have broad access — additional checks at the API layer may not be necessary. Your existing access controls do the work.
Known documents
If your source system already tracks which documents belong to which users, you can rely on that. Before calling CX Platform, your application checks that the logged-in user is authorised to view the document, and only then makes the request.
Verify each request
The most thorough option. Before showing a document to a user, your system independently verifies the request by checking the document's metadata against the user's identity. It's the safest approach but does mean roughly twice the number of API calls per document view, so it's typically used when the other options aren't a fit.
Which approach should you use?
For most customer-facing integrations, HMAC signatures give you strong protection with the least amount of work. For internal tools, trusted user access is usually enough. Your development team can choose what fits best based on how the integration will be used.
Error handling
The API uses standard HTTP response codes, so your developers will recognise what they mean straight away. A 200 means everything worked, 400 means the request was invalid, and 401 means it wasn't authorised — usually due to an issue with the API key, the calling IP address, or permission to access that particular endpoint.
These codes are consistent across every API call, so error handling can be built once and reused.
What's next
This overview gives you the lay of the land. When you're ready to start building, your development team can pick up the detailed API reference for request and response formats, field definitions, and example payloads. If you're not sure where to start, get in touch and we'll point you in the right direction based on what you're trying to achieve.