Help

Developer API

Connect your software to Rapportly through explicit actions for sources, processing, results and management. This guide describes the available API within the documented release limits. The user, rights, storage and credits remain tied to the Rapportly account.

Prepare your integration in three steps

1. 1
   Choose the user, environment and rights

   Open Account → Integrations. Use a separate test key for the fictional simulator and a separate production key for real actions with fictional data. Ask the administrator to grant only required rights and an appropriate budget.

2. 2
   Practise acceptance and failures

   Use the simulator first. Then import the API contracts and review synthetic examples. Keep secrets in your own server settings; collection mutations are disabled by default.

3. 3
   Follow a complete request

   Save the input and request key, check acceptance and completion, read the result, download an available file and inspect usage. Run that trial only in a released environment.

Create your API key

Base URL

https://api.rapportly.io/api/rapportly/v1

The key belongs to a user

A key delegates the rights of one user. The administrator sets the environment, permission ceiling, monthly budget and expiry. A team member activates a prepared key and sees its secret once. Every request also checks current user, package and object permissions. Key management uses a user session; production actions use an API key. Store secrets on your server and revoke a lost key through Account → Integrations. Existing Zapier events follow their own contract.

GET https://api.rapportly.io/api/rapportly/v1/ping
Authorization: Bearer rply_<jouw_sleutel>

Use concrete contracts and examples

The production OpenAPI describes concrete source contracts and labels partial inputs or responses. The inventory identifies schemas still open. The Postman collection defaults to an invalid address, empty credentials and disabled mutations. Import for review and send requests deliberately in a released environment with fictional data. Import has not yet been tested.

• Download the production OpenAPI
• Download the synthetic Postman collection
• Download the source-to-result and download guide
• Download the schema inventory with open items

Practise with fictional requests first

Create a separate test key and practise how your software handles a pending request, a result, a failure and an insufficient budget. The practice environment uses fixed example content and consumes no credits.

1. In Account → Integrations, create or activate a key with the Test environment and the action permissions you want to practise.
2. Request GET /test/scenarios. Choose an action id from the response; this list reflects your current key permissions.
3. Send POST /test/opdrachten with only actie and scenario. Choose succes, verwerking_mislukt, creditbudget_bereikt or toegang_geweigerd. Use a separate Idempotency-Key for every new practice request.
4. Save opdracht_id. When status is bezig, wait about five seconds before reading GET /test/opdrachten/{id}. Always check status: HTTP200 can also contain a failed processing result.

POST https://api.rapportly.io/api/rapportly/v1/test/opdrachten
Authorization: Bearer rply_test_<jouw_testsleutel>
Idempotency-Key: test-rapport-0001
Content-Type: application/json

{
  "actie": "rapport.start",
  "scenario": "succes"
}

This example requires rapport.start to appear in your action list. After a connection problem, repeat the same body with the same Idempotency-Key.

• Download the practice environment guide
• Download the importable Postman practice collection
• Download the practice environment OpenAPI specification

Fetch only what you need

Search accessible client folders, conversations and reports. Read /acties for connected actions and permissions, /gebruik for budget and reservations and /verzoeken for technical request history. Processing still in progress has no result yet. Report-file download links last 15 minutes; read the report again for a new link.

Update customer management

Your software can update office templates, save personal searches, record a visit and create a trajectory. Use the appropriate management permissions and confirm each change. Read the current version first and retain the same request key if a response is lost. Replaying an old request must not revert a newer change. The production test checks searches, visits and trajectories, including cleanup and key revocation. Office templates were only read; writes were tested locally and in CI. The downloadable guide describes the four routes and their evidence limits.

Compare two saved versions

Compare two existing version numbers of the same saved report text field or conversation field without starting new AI processing. This contract was tested locally and in CI; the CRM production test does not establish comparison behaviour in production. Missing history is not replaced with the current text. Long differences are explicitly truncated to at most 8,000 characters per side. This does not compare PowerPoint, quotation calculations, cover letters or formatting. Current read permissions and privacy requirements still apply.

Request an estimate before starting

Use POST /generatieplan to request expected steps and credits for a report, quote or conversation bundle. The key needs gebruik:lezen. Rapportly uses the same calculation and team settings as the website.

An estimate starts no processing and charges no credits. It is not a guaranteed maximum price; also display uncertainties, such as unknown file-reading costs. Starting the actual task rechecks permissions and available credits.

Download the cost estimate guide with request example and response explanation

Start processing from your own software

The API connects case and document starts, uploads, audio and transcription, client folders, styles, output, workflows, Excel and targeted message actions. Each route has its own input, permissions, confirmation and version checks. Existing processing and credit accounting still apply. A start response proves receipt; read the specific status afterwards. The inventory identifies contracts still open.

Create a dossier first

Generate and save a unique UUID in your own software. Send PUT /dossiers/{id} with only naam (up to 200 characters). You receive 201 when it is created and 200 for an identical retry. The dossier belongs to the user and organisation linked to the key. Creating a dossier uses no credits. This route never overwrites anything: different input returns 409; an inaccessible or deleted dossier returns 404. GET /dossiers/{id} reads the current name and klant_id with read permission.

PUT https://api.rapportly.io/api/rapportly/v1/dossiers/00000000-0000-4000-8000-000000000002
Authorization: Bearer rply_<jouw_sleutel>
Content-Type: application/json

{ "naam": "Voorbeeldproject" }

Report, quote or presentation

Start with dossierId and notities. tier is optional: basis, standaard or max. Without a style profile, the document uses neutral formatting. You can also supply an existing accessible stijlprofielId, klantId, bronOpnameIds or taal. The server checks that the selected style matches the document type. Quotes use your saved business settings and controlled quote numbering; the API does not send the quote to the customer.

POST https://api.rapportly.io/api/rapportly/v1/rapporten
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-rapport-2026-0001
Content-Type: application/json

{
  "dossierId": "00000000-0000-4000-8000-000000000002",
  "notities": "Team Atlas besprak de training. Noor plant de volgende bijeenkomst op donderdag.",
  "tier": "standaard"
}

Save versie_id from the response and poll GET /rapporten/{versie_id}, including for quotes and presentations. Files become available inside resultaat when status is klaar: resultaat.export_url is the PDF, resultaat.export_url_docx is the Word file and resultaat.export_url_pptx is the PowerPoint when available. Download links expire after 15 minutes. Fetch the result again for new links. If status is mislukt, do not automatically submit a new key; check the processing status and usage in Rapportly first.

Download the source-to-result and download guide

Upload your own style examples

Let your software submit one to three example files as a complete set. Rapportly uses the same file checks and style processing as the website. The task belongs to the linked user and uses that user’s storage and available credits.

1. Send the files with a name, document type, personal or team sharing, explicit confirmation and a stable request key. A team style requires an administrator or team leader.
2. Store the receipt ID and read the status. Receipt means the complete set is safely recorded; any required example review and approval follow separately.
3. After an interruption, repeat exactly the same request. This does not create a second style. Incomplete uploads can be retried for thirty days and are safely removed afterward.

Download the style examples guide, including a multipart example and error handling

Connect your calendar or mailbox

Let the user approve access at Google or Microsoft. Your software can track the request and intentionally disconnect. Provider passwords and tokens stay out of API responses.

Use verbindingen:beheren for connections and agenda:lezen for events. Sending additionally requires a separate permission and intentional action.

Keep the request ID, idempotency key and current basis. Repeat a lost request exactly; an old disconnect must not remove a later connection.

You can also choose your default mailbox through the API. Both connection management and sending permission are required. Read the current preference and connection first; an old retry preserves a newer choice and existing outbox requests retain their sender.

Download the consent, events, disconnect and recovery guide

Conversation bundle from text

Send a transcript of at least one hundred characters. The response returns gesprek_id so you can follow the result. Optional fields: titel, tier, klantId, and taal.

POST https://api.rapportly.io/api/rapportly/v1/gesprekken
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-gesprek-2026-0001
Content-Type: application/json

{
  "transcript": "Team Atlas bespreekt uitsluitend een fictieve oefening. Het team plant een training en verzamelt algemene voorbeeldvragen zonder klantgegevens.",
  "titel": "Kennismaking"
}

Read existing language variants

Read existing language results. The documented workflow routes for starting, pausing, resuming and recovery were tested locally and in CI; the CRM production test does not verify language processing. Use them only in an environment released for that purpose. The original user, key, source and costs remain bound to the request. Current source status, permissions, budget and verified settlement remain required; an expired or deleted source does not authorise a new start. Bulk processing with a second language remains closed, including inherited settings. Paid completion of one missing translation outcome remains excluded.

GET https://api.rapportly.io/api/rapportly/v1/gesprekken/00000000-0000-4000-8000-000000000001/taalvarianten
Authorization: Bearer rply_<jouw_sleutel>

Receive a notification when processing completes

Have Rapportly send a notification to your server. It contains technical references; retrieve the content separately with appropriate read permissions. Your software no longer needs to ask for progress repeatedly.

1. Create an HTTPS receiver on your server. Register it with POST /webhooks using a production key with webhooks:beheren. Use that same key for the processing you want notifications about.
2. Verify the signature over the original message bytes and store every event id uniquely. Acknowledge the event only after storing it durably together with your follow-up task. Repeated events must not create duplicate tasks.
3. Use GET /webhook-afleveringen and the details for each delivery. Rapportly retries temporary failures up to eight times. You can request one extra round after a problem. Accepted means your server accepted the notification; monitor subsequent processing in your system.

• Download the webhook guide with endpoints, limits and recovery steps
• Download the Node.js signature verification example

The fictional practice environment sends no real notifications. Test your receiver with fictional data and a separate production integration. The code example verifies the message; your server is responsible for storage and follow-up actions.

What does an error mean?

Protect the key and customer data

• Use the key only on your server, never in public browser code.
• Create a separate key for each integration and revoke old keys.
• Keep keys, results, and temporary download links out of public logs and chats.
• Store retrieved customer data according to your own system's access rules.