MOBILE-ID · TRUSTED LTANS

Transfer API

Initiate transfer, inspect results and acknowledge the correct transfer; export does not itself change custody or delete sources.

VI–EN terminology

A verifiable handover package

Inventory

Inventory exported content bytes, evidence and context.

Recipient verification

Reconcile components, digests and independent verifiability.

`Acknowledgement`

Record conditions and custody handover point.

openapi.yaml openapi.json asyncapi.yaml postman-target.json

LOCAL SIMULATION · Target contracts · No network requests

POST/v1/archives/{archiveId}/transfers

TARGET CONTRACT · API 3.0.0-draft

Job TransferRequest Errors and recovery TransferStarted

Property	Value
Technical owner	Archive Service
Application scope	transfers:write
HTTP	202
Call processing	Asynchronous work: inspect Job and the result-resource state.
Event	TransferStarted

Keep source custody; verify manifest and recipient acknowledgement.

cURL

curl --fail-with-body --request POST \
  "${BASE_URL%/}/v1/archives/${ARCHIVE_ID}/transfers" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary "@${REQUEST_FILE}"

Request JSON

{
  "exportId": "exp-test-001",
  "destinationProfileId": "destination-test-001",
  "approvalId": "approval-test-002"
}

Target response

{
  "jobId": "job-transfer-001",
  "state": "QUEUED",
  "resourceId": "trf-test-001",
  "correlationId": "corr-test-001",
  "pollAfterSeconds": 2
}

JSON Schema

{
  "type": "object",
  "properties": {
    "exportId": {
      "type": "string"
    },
    "destinationProfileId": {
      "type": "string"
    },
    "approvalId": {
      "type": "string"
    }
  },
  "required": [
    "exportId",
    "destinationProfileId",
    "approvalId"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "exportId": "exp-test-001",
      "destinationProfileId": "destination-test-001",
      "approvalId": "approval-test-002"
    }
  ]
}

application/problem+json

{
  "type": "https://example.invalid/problems/transfer-not-acknowledged",
  "title": "Transfer Not Acknowledged",
  "code": "TRANSFER_NOT_ACKNOWLEDGED",
  "detail": "Recipient verification has not been acknowledged.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Archive Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

GET/v1/transfers/{transferId}

TARGET CONTRACT · API 3.0.0-draft

TransferResult Errors and recovery

Property	Value
Technical owner	Archive Service
Application scope	transfers:read
HTTP	200
Call processing	Authentication/authorization → HTTP handling; not a resource-state enum.
Event	Audit or internal event

Keep source custody; verify manifest and recipient acknowledgement.

cURL

curl --fail-with-body --request GET \
  "${BASE_URL%/}/v1/transfers/${TRANSFER_ID}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}"

Target response

{
  "transferId": "trf-test-001",
  "archiveId": "arc-test-001",
  "exportId": "exp-test-001",
  "recipientId": "recipient-test-001",
  "state": "AWAITING_ACKNOWLEDGEMENT",
  "scope": "Complete manifest inventory for exp-test-001; cryptographic verification outside this synthetic example",
  "jobId": "job-transfer-001",
  "packageDigest": {
    "algorithm": "SHA-256",
    "value": "5c34a84b064c4aa79bbc8f49cadeea9c55cfc9df10d655e9bc6f7a6af248e1c1"
  }
}

JSON Schema

{
  "type": "object",
  "properties": {
    "transferId": {
      "type": "string",
      "pattern": "^trf-"
    },
    "archiveId": {
      "type": "string",
      "pattern": "^arc-"
    },
    "exportId": {
      "type": "string",
      "pattern": "^exp-"
    },
    "recipientId": {
      "type": "string"
    },
    "scope": {
      "type": "string",
      "minLength": 1
    },
    "state": {
      "type": "string",
      "enum": [
        "QUEUED",
        "TRANSFERRING",
        "AWAITING_ACKNOWLEDGEMENT",
        "ACKNOWLEDGED",
        "REJECTED",
        "FAILED"
      ]
    },
    "jobId": {
      "type": "string"
    },
    "packageDigest": {
      "$ref": "#/components/schemas/Digest"
    },
    "acknowledgementId": {
      "type": "string"
    },
    "acceptedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "transferId",
    "archiveId",
    "exportId",
    "recipientId",
    "scope",
    "state",
    "jobId",
    "packageDigest"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "transferId": "trf-test-001",
      "archiveId": "arc-test-001",
      "exportId": "exp-test-001",
      "recipientId": "recipient-test-001",
      "state": "AWAITING_ACKNOWLEDGEMENT",
      "scope": "Complete manifest inventory for exp-test-001; cryptographic verification outside this synthetic example",
      "jobId": "job-transfer-001",
      "packageDigest": {
        "algorithm": "SHA-256",
        "value": "5c34a84b064c4aa79bbc8f49cadeea9c55cfc9df10d655e9bc6f7a6af248e1c1"
      }
    }
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "state": {
            "const": "ACKNOWLEDGED"
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "acknowledgementId",
          "acceptedAt"
        ]
      }
    }
  ]
}

application/problem+json

{
  "type": "https://example.invalid/problems/transfer-not-acknowledged",
  "title": "Transfer Not Acknowledged",
  "code": "TRANSFER_NOT_ACKNOWLEDGED",
  "detail": "Recipient verification has not been acknowledged.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Archive Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

POST/v1/transfers/{transferId}/acknowledgements

TARGET CONTRACT · API 3.0.0-draft

The recipient binds transferId, exportId, recipientId, digest and scope. Backend must match authenticated identity, reject mismatches and retain an audited statement.

TransferResult TransferAcknowledgement Errors and recovery TransferCompleted

Property	Value
Technical owner	Archive Service
Application scope	transfers:acknowledge
HTTP	201
Call processing	Authentication/authorization → HTTP handling; not a resource-state enum.
Event	TransferCompleted

Keep source custody; verify manifest and recipient acknowledgement.

cURL

curl --fail-with-body --request POST \
  "${BASE_URL%/}/v1/transfers/${TRANSFER_ID}/acknowledgements" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary "@${REQUEST_FILE}"

Request JSON

{
  "transferId": "trf-test-001",
  "exportId": "exp-test-001",
  "recipientId": "recipient-test-001",
  "packageDigest": {
    "algorithm": "SHA-256",
    "value": "5c34a84b064c4aa79bbc8f49cadeea9c55cfc9df10d655e9bc6f7a6af248e1c1"
  },
  "verificationReportReference": "urn:ltans:synthetic:recipient-report-001",
  "scope": "Complete manifest inventory for exp-test-001; cryptographic verification outside this synthetic example",
  "acceptedAt": "2026-10-15T09:00:00Z"
}

Target response

{
  "transferId": "trf-test-001",
  "archiveId": "arc-test-001",
  "exportId": "exp-test-001",
  "recipientId": "recipient-test-001",
  "state": "ACKNOWLEDGED",
  "scope": "Complete manifest inventory for exp-test-001; cryptographic verification outside this synthetic example",
  "jobId": "job-transfer-001",
  "packageDigest": {
    "algorithm": "SHA-256",
    "value": "5c34a84b064c4aa79bbc8f49cadeea9c55cfc9df10d655e9bc6f7a6af248e1c1"
  },
  "acknowledgementId": "ack-test-001",
  "acceptedAt": "2026-10-15T09:00:00Z"
}

JSON Schema

{
  "type": "object",
  "properties": {
    "transferId": {
      "type": "string",
      "pattern": "^trf-"
    },
    "exportId": {
      "type": "string",
      "pattern": "^exp-"
    },
    "recipientId": {
      "type": "string"
    },
    "packageDigest": {
      "$ref": "#/components/schemas/Digest"
    },
    "verificationReportReference": {
      "type": "string",
      "format": "uri-reference"
    },
    "scope": {
      "type": "string",
      "minLength": 1
    },
    "acceptedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "transferId",
    "exportId",
    "recipientId",
    "packageDigest",
    "verificationReportReference",
    "scope",
    "acceptedAt"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "transferId": "trf-test-001",
      "exportId": "exp-test-001",
      "recipientId": "recipient-test-001",
      "packageDigest": {
        "algorithm": "SHA-256",
        "value": "5c34a84b064c4aa79bbc8f49cadeea9c55cfc9df10d655e9bc6f7a6af248e1c1"
      },
      "verificationReportReference": "urn:ltans:synthetic:recipient-report-001",
      "scope": "Complete manifest inventory for exp-test-001; cryptographic verification outside this synthetic example",
      "acceptedAt": "2026-10-15T09:00:00Z"
    }
  ],
  "description": "Recipient statement for the exact transfer/package/scope. Server must bind authenticated recipient and path transferId, compare exportId and packageDigest, authorize scope, and preserve the statement. Digest alone is not an acknowledgement or proof of cryptographic verification."
}

application/problem+json

{
  "type": "https://example.invalid/problems/transfer-not-acknowledged",
  "title": "Transfer Not Acknowledged",
  "code": "TRANSFER_NOT_ACKNOWLEDGED",
  "detail": "Recipient verification has not been acknowledged.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Archive Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

Transfer API

A verifiable handover package

Inventory

Recipient verification

`Acknowledgement`

Next steps

Search LTANS documentation