API-Dokumentation

Authentifizierung

API-Keys werden im Dashboard unter Einstellungen → API-Keys erstellt. Jeder Key wird als SHA-256-Hash gespeichert und nur einmalig bei der Erstellung angezeigt.

Senden Sie den Key als Bearer-Token im Authorization-Header:

httpAuthorization: Bearer at_your_key_here

Basis-URL: https://12personatypen.de/api/v1

Bewerber einladen

POST /api/v1/invites

Request

httpPOST https://12personatypen.de/api/v1/invites
Authorization: Bearer at_your_key_here
Content-Type: application/json

{
  "name": "Max Mustermann",
  "email": "max@beispiel.de",
  "external_id": "crm-lead-123",  // optional, für CRM-Matching
  "send_email": true               // optional, default true
}

Response

json{
  "ok": true,
  "invite_url": "https://12personatypen.de/t/abc123...",
  "candidate_token": "abc123...",
  "external_id": "crm-lead-123"
}

Alle Kandidaten abrufen

GET /api/v1/candidates

Request

httpGET https://12personatypen.de/api/v1/candidates
Authorization: Bearer at_your_key_here

Query-Parameter

Response

json{
  "candidates": [
    {
      "id": 1,
      "external_id": "crm-lead-123",
      "name": "Max Mustermann",
      "email": "max@beispiel.de",
      "status": "abgeschlossen",
      "created_at": "2026-07-08T12:00:00Z",
      "completed_at": "2026-07-08T12:15:00Z",
      "scores": {
        "overall": 72,
        "fit": { "key": "B", "label": "Solides Potenzial" },
        "archetype": { "key": "jaeger", "name": "Der Jäger" },
        "dimension_scores": [...],
        "warnings": [...]
      }
    }
  ]
}

Einzelner Kandidat

GET /api/v1/candidates/:id

Abruf per interner ID oder external_id:

httpGET https://12personatypen.de/api/v1/candidates/1
GET https://12personatypen.de/api/v1/candidates/crm-lead-123  // per external_id
Authorization: Bearer at_your_key_here

Response: Einzelner Kandidat mit vollständigen Scores (gleiches Format wie in der Listen-Response).

Webhooks

Webhooks werden im Dashboard unter Einstellungen konfiguriert. Aktuell wird das Event candidate.completed unterstützt.

Headers

Payload

json{
  "event": "candidate.completed",
  "data": {
    "candidate": {
      "id": 1,
      "name": "Max Mustermann",
      "email": "max@beispiel.de",
      "external_id": "crm-lead-123"
    },
    "scores": {
      "overall": 72,
      "fit": { "key": "B", "label": "Solides Potenzial" },
      "archetype": {
        "key": "jaeger",
        "name": "Der Jäger",
        "subtitle": "Zielstrebig & hartnäckig"
      },
      "dimensionScores": [
        { "key": "abschluss", "name": "Abschlussstärke", "score": 85 },
        ...
      ],
      "warnings": []
    },
    "reportUrl": "https://12personatypen.de/dashboard/kandidat/1"
  },
  "timestamp": "2026-07-08T12:15:00.000Z"
}

Signatur verifizieren

javascriptconst crypto = require('crypto');

const signature = request.headers['x-salesdna-signature'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}

Integrationsbeispiele

Zapier

1. Trigger: "Neuer Kontakt in CRM"
2. Action: "Webhooks by Zapier" → POST
3. URL: https://12personatypen.de/api/v1/invites
4. Headers: Authorization: Bearer at_your_key
5. Body: { "name": "{{name}}", "email": "{{email}}", "external_id": "{{id}}" }

Make (Integromat)

1. Trigger: Watch new records in CRM
2. Module: HTTP → Make a request
3. URL, Headers und Body wie bei Zapier

cURL

bashcurl -X POST https://12personatypen.de/api/v1/invites \
  -H "Authorization: Bearer at_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Max Mustermann","email":"max@beispiel.de","external_id":"crm-123"}'

Rate Limits

Maximal 100 Requests pro Minute pro API-Key. Bei Überschreitung wird HTTP 429 zurückgegeben.

Fehler-Responses