Import consent records

POST /v1/jobs/consent-imports · permission consent-records:write

Imports acceptances of your legal documents that were recorded in another system, for example when you move users to KeenAuth. The request is synchronous: 1–500 records are written in one transaction, so either all of them are written or none is. Every imported record has method = import, and occurred_at keeps the time from the source system. The version, content hash and locale are taken from the document; you cannot supply them. Imported records are append-only like every other consent record. To record a single acceptance obtained now, use Record a consent.

Idempotency-Key is required. A retry with the same key and request returns the same response (with Idempotent-Replayed: true) and writes nothing a second time.

Request

JSON body (unknown fields are rejected with 400 unknown_field):

Field Type Required Description
records object[] yes 1–500 records, written in this order.
records[].user_id string yes User ID (usr_…).
records[].subject_type string yes Only document.
records[].subject_id string yes Legal document ID (ldoc_…).
records[].state string yes presented, accepted or declined.
records[].application_id string | null no Application (app_…); when omitted and the document is application-specific, the document's application is recorded.
records[].occurred_at string (date-time) yes When it happened in the source system; not in the future.

Response

201 Created with the written records (records), in input order.

{
  "imported_count": 1,
  "records": [
    {
      "id": "crec_01j9xk3m7q8r2s4t6v8w0y2z4b",
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4c",
      "subject_type": "document",
      "subject_id": "ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "subject_version": "2026-10",
      "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "locale": "en",
      "state": "accepted",
      "method": "import",
      "application_id": null,
      "occurred_at": "2025-03-14T08:00:00Z"
    }
  ]
}

Errors

HTTP code When
400 malformed_request, unknown_field The Idempotency-Key header is missing or malformed, the body is not valid JSON, or it has an unknown field.
401 unauthenticated The credential is missing, invalid or revoked.
403 insufficient_permissions The credential lacks the required permission.
413 payload_too_large The body is larger than 1 MiB.
415 unsupported_media_type The content type is not application/json.
422 validation_failed A record is invalid; errors[].pointer is /records/<index>/<field>. An unknown user is unknown_user, an unknown application unknown_application, an unknown document unknown_subject; fewer than 1 or more than 500 records is out_of_range at /records. Nothing is written.
422 idempotency_key_reuse The Idempotency-Key was used with a different request.
429 rate_limited The rate limit was exceeded; retry after the Retry-After period.
503 service_unavailable A dependency is temporarily unavailable; retry after the Retry-After period.

Example

curl -X POST https://api.eu.keenauth.com/v1/jobs/consent-imports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"records":[{"user_id":"usr_01j9xk3m7q8r2s4t6v8w0y2z4c","subject_type":"document","subject_id":"ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a","state":"accepted","occurred_at":"2025-03-14T08:00:00Z"}]}'

CLI: keenauth jobs consent-imports create --data records.json

Personal data

This endpoint carries personal data: consent records. Personal data in the KeenAuth APIs describes what is stored, how long it is kept and how it is deleted. Do not send special categories of personal data (health, biometric data, religion, political opinions, sexual orientation) in any field.