API-overzicht

API-calls maken naar ProcessMind

Deze gids bevat voorbeelden en best practices voor het aanroepen van de ProcessMind API om data op te halen, informatie te versturen of workflows te automatiseren.

Bekijk de API Reference voor volledige endpointdocumentatie met request- en response-indelingen.

Ga voor meer voorbeelden en clientbibliotheken naar de API Documentation on GitHub.

Basis-URL van de API

Alle API-verzoeken moeten naar het volgende adres worden gestuurd:

https://api.processmind.com

Alle routes zijn versiegebonden onder /v1. De volledige machineleesbare API-specificatie is beschikbaar als OpenAPI 3.1 op:

GET https://api.processmind.com/v1/openapi.json

Authenticatie

Voor alle API-verzoeken is je API-sleutel in de header x-api-key vereist:

x-api-key: your-api-key-here

Je haalt de API-sleutel op via de accountinstellingen van ProcessMind. Zie Getting your API Key voor instructies.

Statuscodes

De API van ProcessMind gebruikt standaard HTTP-statuscodes:

Belangrijke concepten

• apiKey: je authenticatietoken voor alle API-requests.
• tenantId: identificeert de context van je workspace of organisatie. Je vindt deze in de accountinstellingen.
• datatableId: identificeert een specifieke datatabel voor datahandelingen. Beschikbaar via de optie ID van datatabel ophalen in het datasetinstellingenmenu binnen ProcessMind.

Wat je kunt doen

Met de ProcessMind API kun je:

• Tenants beheren: tenantinformatie ophalen, instellingen bijwerken en statistieken bekijken
• Gebruikers beheren: gebruikers toevoegen, bijwerken of verwijderen uit tenants en organisaties
• Processen beheren: processen maken, BPMN-modellen uploaden en ordenen in mappen
• Data koppelen: datatables aan processen koppelen voor analyse
• Data uploaden: CSV/XLSX-bestanden rechtstreeks naar datatables uploaden
• Datasets beheren: datasets en datatables weergeven, inspecteren en verwijderen

Veelgebruikte voorbeelden

Hieronder staan praktische voorbeelden van veelgebruikte handelingen met de ProcessMind API.

Een presigned upload-URL ophalen

Haal eerst een presigned URL op om een bestand naar een datatable te uploaden:

const presignedUrl = await getPresignedUploadUrl({
	apiKey,
	tenantId: "tenant-123",
	datatableId: "table-456"
});
console.log(presignedUrl); // https://s3.amazonaws.com/…?X-Amz-Signature=…

Datasets weergeven

Haal alle datasets in je tenant op:

const datasets = await getDatasets({
	apiKey,
	tenantId: "tenant-123"
});
console.log(datasets);

Tenantinformatie ophalen

Haal gegevens over je tenant op:

const tenantInfo = await getTenant({
	apiKey,
	tenantId: "tenant-123"
});
console.log(tenantInfo);

Een proces maken

Maak een nieuw proces in je tenant:

const process = await createProcess({
	apiKey,
	tenantId: "tenant-123",
	displayName: "Order to Cash"
});
console.log(process.id); // Use this ID for subsequent operations

Een BPMN-model uploaden

Upload een BPMN-bestand om je procesmodel te definiëren:

const fs = require("fs");
const bpmnXml = fs.readFileSync("./my-process.bpmn", "utf8");

await uploadBpmn({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	bpmnXml
});

Data aan een proces koppelen

Koppel een datatable aan een proces voor analyse:

const mapping = await createProcessMapping({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	dataTableId: "datatable-789",
	displayName: "Sales Data 2024",
	showByDefault: true
});

Een gebruiker aan een tenant toevoegen

Voeg een gebruiker aan je tenant toe:

const result = await addTenantUser({
	apiKey,
	tenantId: "tenant-123",
	id: "user-456",
	email: "colleague@example.com",
	isAdminInTenant: false,
	isActiveInTenant: true,
	sendInvitationEmail: true
});

Opmerking: Rolvelden in de body (isAdminInTenant, access, isDashboardViewer) worden letterlijk overgenomen. De endpoints voor gebruikersbeheer bieden volledige tenantbeheermogelijkheden. Geef daarom alleen API-sleutels met schrijfrechten uit aan aanroepers die je vertrouwt met beheerdersrechten. De System API verstuurt geen uitnodigingsmail. Je bent zelf verantwoordelijk voor het onboarden van de gebruiker.

Bestanden uploaden

De algemene werkwijze voor het uploaden van een bestand naar ProcessMind is:

1. Haal een presigned URL op met de call getPresignedUploadUrl.
2. Voer een PUT-verzoek uit naar die URL met de inhoud van het bestand.
3. De presigned URL geeft rechtstreeks toegang tot de cloudopslag voor de upload. Extra inloggegevens zijn niet nodig.

Hier is een vereenvoudigd voorbeeld met fetch:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Step 1: Obtain a presigned URL
	const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
	
	// Step 2: Upload the file via PUT
	await fetch(uploadUrl, {
		method: "PUT",
		headers: {
			"Content-Type": file.type
		},
		body: file
	});
}

Volledige voorbeelden

Hieronder staan volledige, direct te kopiëren voorbeelden in verschillende programmeertalen.

Bash-voorbeeld: een bestand uploaden

Minimaal Bash-script om een bestand naar ProcessMind te uploaden met twee curl-calls en placeholders voor alle waarden

#!/bin/bash
# Minimal Bash script to upload a file to ProcessMind using two curl calls, with placeholders for all values

# Replace the following placeholders with your actual values:
# <API_KEY>, <TENANT_ID>, <DATATABLE_ID>, <FILE_PATH>

curl -s -H "x-api-key: <API_KEY>" \
	"https://api.processmind.com/v1/tenant/<TENANT_ID>/datatables/<DATATABLE_ID>/uploads/presigned-url" \
	| grep -oP '"PreSignedUploadUrl"\s*:\s*"\K[^"]+' \
	| xargs -I {} curl -s -X PUT --upload-file "<FILE_PATH>" "{}"

Node.js-voorbeeld: een lokaal CSV-bestand uploaden

Uploadt een lokaal CSV-bestand naar ProcessMind met een presigned URL.

Stappen:

1. Haal een presigned upload-URL op via de API.
2. Lees het lokale bestand van schijf.
3. Upload het bestand naar de presigned URL met HTTP PUT.

Configuratie:

• Geef je API-sleutel, tenantId, datatableId en filePath door bij het aanroepen van uploadFile().
• De basis-URL van de API is ingesteld op https://api.processmind.com

/**
 * Uploads a local CSV file to ProcessMind using a presigned URL.
 *
 * Steps:
 * 1. Fetch a presigned upload URL from the API.
 * 2. Read the local file from disk.
 * 3. Upload the file to the presigned URL using HTTP PUT.
 *
 * Configuration:
 * - Provide your API key, tenantId, datatableId, and filePath when calling uploadFile().
 * - The API base URL is set to https://api.processmind.com
 */

const fs = require("node:fs");

/**
 * Uploads a file to ProcessMind datatable using a presigned URL.
 * @param {string} apiKey - Your API key for authentication.
 * @param {string} tenantId - Your tenant identifier.
 * @param {string} datatableId - Your datatable identifier.
 * @param {string} filePath - Path to the file to upload.
 */

async function getApi({path, apiKey, apiUrl = "https://api.processmind.com"}) {
	try {
        const response = await fetch(`${apiUrl}${path}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey
            }
        });
        const body = await response.json();
        if (!response.ok) {
            console.error(`Error loading from API: ${response.status}, ${response.statusText}: ${body.message}`);
            return;
        }
        return body;
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

async function getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl = "https://api.processmind.com"}) {
	return (await getApi({apiKey, path: `/v1/tenant/${tenantId}/datatables/${datatableId}/uploads/presigned-url`, apiUrl})).PreSignedUploadUrl;
}

async function getDatasets({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/datasets`, apiUrl});
}

async function getTenant({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}`, apiUrl});
}

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/organization`, apiUrl});
}

async function uploadFile({apiKey, tenantId, datatableId, filePath, apiUrl = "https://api.processmind.com"}) {
    try {
        const uploadUrl = await getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl});

		console.log("Uploading file...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Error reading file:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Upload failed:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("File uploaded successfully.");
                }
            } catch (uploadErr) {
                console.error("Error uploading file:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

// Export the function for use in other modules
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Python-voorbeeld: een lokaal CSV-bestand uploaden

Uploadt een lokaal CSV-bestand naar een externe API met een presigned URL.

Stappen:

1. Haal een presigned upload-URL op via de API.
2. Lees het lokale bestand van schijf.
3. Upload het bestand naar de presigned URL met HTTP PUT.

Configuratie:

• Werk api_key, tenant_id, datatable_id en file_path naar behoefte bij.

"""
Uploads a local CSV file to a remote API using a presigned URL.

Steps:
1. Fetch a presigned upload URL from the API.
2. Read the local file from disk.
3. Upload the file to the presigned URL using HTTP PUT.

Configuration:
- Update api_key, tenant_id, datatable_id, file_path as needed.
"""

import requests

# === Configuration ===
api_key = ""  # API key for authentication
tenant_id = ""  # Tenant identifier
datatable_id = ""  # Datatable identifier
file_path = ""  # Path to the file to upload


print("Fetching upload URL...")
api_url = "https://api.processmind.com"  # Base API URL
presign_url = f"{api_url}/v1/tenant/{tenant_id}/datatables/{datatable_id}/uploads/presigned-url"
presign_res = requests.get(presign_url, headers={"x-api-key": api_key})
if not presign_res.ok:
	print(f"Error fetching upload URL: {presign_res.status_code}, {presign_res.reason}: {presign_res.text}")
	exit(1)

presign_body = presign_res.json()
upload_url = presign_body.get("PreSignedUploadUrl")
if not upload_url:
	print("No presigned upload URL returned.")
	exit(1)

print("Uploading file...")
with open(file_path, "rb") as f:
	upload_res = requests.put(upload_url, data=f)
if not upload_res.ok:
	print(f"Upload failed: {upload_res.status_code}, {upload_res.reason}")
else:
	print("File uploaded successfully.")

Paginering

Lijst-endpoints accepteren de queryparameters limit en offset en retourneren een onbewerkte JSON-array, zonder wrapper en zonder totaal aantal:

GET /v1/tenant/{tenantId}/processes?limit=50&offset=100

Vraag voor paginering door alle resultaten steeds opnieuw op met offset += limit totdat de response-array korter is dan de aangevraagde limit, of leeg is. Waarden boven het maximum worden afgewezen met 400. De versiegebonden data-endpoints, zoals datasets, datatables, versies en webhooks, volgen dezelfde afspraak.

Versiebeheer en uitfasering

• Alle routes zijn versiegebonden onder /v1. Wijzigingen die niet compatibel zijn, verschijnen in een nieuwe versie in plaats van dat /v1 stilzwijgend verandert.
• Uitfaseringen worden minstens 6 maanden voordat een route wordt verwijderd aangekondigd in de changelog en op deze pagina. Uitgefaseerde routes blijven in die periode werken.
• Responses van uitgefaseerde routes bevatten een header Sunset met de verwijderdatum en Deprecation: true.
• Belangrijke wijzigingen die clients raken, staan altijd in de changelog. Schrijf je in of controleer de changelog voordat je vastgezette API-clients bijwerkt.

Volgende stappen

• API Reference: volledige documentatie voor alle endpoints met request- en response-indelingen
• GitHub-voorbeelden: downloadbare voorbeelden en clientbibliotheken
• Getting your API Key: zo verkrijg en beheer je je API-sleutel