Sustema

ENTITY developer reference

Look up an identifier

Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.

This is a documentation reading view of an unreleased candidate, not a downloadable replacement schema. Public wire names, types and constraints are retained except for the explicitly marked private-only subsets and route patterns. Private governance references are explained in public language. Use only a separately released, verified generation for clients. Read the explicit exclusions.

POST /v1/identifier-lookups

Operation identifier: lookupIdentifier

Look up an identifier

Entity-Service-Profile carries the accepted profile_id; the endpoint pins its separate immutable revision. The retained template parameter description says “revision”; follow this current interpretation when reading that historical wording. No reserved example URL in the definitions is a live service destination.

Authentication

Apply the operation’s security requirement when present, otherwise the contract default below. These definitions do not provision access or qualify an authentication flow.

[
  {
    "bearerAuth": []
  }
]
Security scheme definitions
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Validated OAuth access token, never an ID token. Issuer/audience/token endpoint and scope mapping are deployment-profile values. ENTITY current role, data and budget policy additionally applies."
  }
}

Request parameters

Headers, path and query parameters from the candidate contract. Operation-specific definitions take precedence over inherited definitions with the same name and location. Request body fields appear in the reading view below.

Entity-Service-Profile

header · Required

Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation.

Reading definition for Entity-Service-Profile
{
  "name": "Entity-Service-Profile",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "maxLength": 4096,
    "x-profile-maxLength": "string_characters_max"
  },
  "description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
}

Idempotency-Key

header · Required

Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics.

Reading definition for Idempotency-Key
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "maxLength": 36
  },
  "description": "Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics."
}

Entity-Operation-Created-At

header · Required

Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry.

Reading definition for Entity-Operation-Created-At
{
  "name": "Entity-Operation-Created-At",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "format": "date-time",
    "maxLength": 35
  },
  "description": "Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry."
}

Entity-Max-Units

header · Optional

Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority.

Schema: Units

Reading definition for Entity-Max-Units
{
  "name": "Entity-Max-Units",
  "in": "header",
  "required": false,
  "schema": {
    "$ref": "#/components/schemas/Units"
  },
  "description": "Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority."
}

Request and response contract

The candidate operation is shown below with the declared documentation-only public-meaning projection. References open the corresponding public schema. No server URL or credential is supplied by this page.

{
  "operationId": "lookupIdentifier",
  "summary": "Look up an identifier",
  "parameters": [
    {
      "$ref": "#/components/parameters/ServiceProfile"
    },
    {
      "$ref": "#/components/parameters/IdempotencyKey"
    },
    {
      "$ref": "#/components/parameters/OperationCreated"
    },
    {
      "$ref": "#/components/parameters/MaxUnits"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful governed response; examples are synthetic and no endpoint is deployed by this specification.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResolutionResponse"
          },
          "example": {
            "data": {
              "outcome": "established",
              "reason_codes": [
                "synthetic_case"
              ],
              "explanation": "Synthetic contract example; no executed matching result.",
              "policy_id": "synthetic-policy-1",
              "completeness": {
                "state": "complete_for_requested_scope",
                "scope": "synthetic-review fixture set",
                "reasons": []
              },
              "entity": {
                "subject": {
                  "entity_id": "00000001-1111-4111-8111-000000000001",
                  "environment": "synthetic-review",
                  "manifest_id": "00000002-1111-4111-8111-000000000002",
                  "subject_type": "legal_entity"
                },
                "lifecycle": {
                  "state": "active",
                  "successors": [],
                  "reason": null,
                  "recorded_at": "2026-09-01T12:10:00Z"
                },
                "publication": {
                  "manifest_id": "00000002-1111-4111-8111-000000000002",
                  "published_at": "2026-09-01T12:15:00Z",
                  "identity_revision": "synthetic-identity-1",
                  "source_checkpoint_refs": [
                    "synthetic-source-1"
                  ],
                  "policy_revision": "synthetic-policy-1",
                  "relationship_revision": null,
                  "classification_revision": null
                },
                "claims": [
                  {
                    "claim_id": "00000003-1111-4111-8111-000000000003",
                    "claim_version_id": "00000004-1111-4111-8111-000000000004",
                    "predicate": "legal_name",
                    "availability": "available",
                    "value": {
                      "kind": "text",
                      "text": "Example Demonstration Limited"
                    },
                    "evidence": {
                      "level": "discovery",
                      "selection_policy_id": "synthetic-selection-1",
                      "linkage_policy_id": "synthetic-linkage-1",
                      "explanation": "Synthetic registered-name fixture; no real source or verification.",
                      "limitations": [
                        "Illustrative data only"
                      ],
                      "confidence_meaning": "qualitative_policy_assessment_not_probability",
                      "assessment": {
                        "assessment_id": "90000000-0000-4000-8000-000000000001",
                        "method_revision": "sei-0.1",
                        "predicate_policy_revision": "synthetic-registered-identity-1",
                        "evaluated_at": "2026-09-09T12:00:00Z",
                        "as_of": {
                          "precision": "unknown"
                        },
                        "source_linkage": {
                          "state": "not_assessed",
                          "score_basis_points": null,
                          "display_percent": null,
                          "zone": null,
                          "zone_label": "Not assessed",
                          "interpretation": "We do not have a usable basis to assess this information.",
                          "explanation": "This older synthetic assertion has no qualified SEI evidence basis.",
                          "meaning": "evidence_index_not_probability",
                          "method_revision": "sli-0.1",
                          "zone_policy_revision": "sez-0.1"
                        },
                        "attribute_support": {
                          "state": "not_assessed",
                          "score_basis_points": null,
                          "display_percent": null,
                          "zone": null,
                          "zone_label": "Not assessed",
                          "interpretation": "We do not have a usable basis to assess this information.",
                          "explanation": "This older synthetic assertion has no qualified SEI evidence basis.",
                          "meaning": "evidence_index_not_probability",
                          "method_revision": "sei-0.1",
                          "zone_policy_revision": "sez-0.1"
                        },
                        "delivered_support": {
                          "state": "not_assessed",
                          "score_basis_points": null,
                          "display_percent": null,
                          "zone": null,
                          "zone_label": "Not assessed",
                          "interpretation": "We do not have a usable basis to assess this information.",
                          "explanation": "This older synthetic assertion has no qualified SEI evidence basis.",
                          "meaning": "evidence_index_not_probability",
                          "method_revision": "sei-0.1",
                          "zone_policy_revision": "sez-0.1"
                        },
                        "conflict": "not_assessed",
                        "explanation": {
                          "summary": "Earlier synthetic fact, not assessed under SEI 0.1.",
                          "reason_codes": [
                            "policy_not_qualified"
                          ],
                          "limiting_factors": [
                            "Synthetic review example; not empirical evidence."
                          ],
                          "next_checks": [
                            "Qualify the applicable source and service profile before live use."
                          ],
                          "scope_statement": "This exact synthetic company, assertion and stated time only."
                        },
                        "calibration_status": "not_calibrated",
                        "disclosure": "permitted_basis",
                        "target": "fact_for_entity_predicate_scope_and_time",
                        "calculation": {
                          "state": "unavailable",
                          "reason": "No SEI basis supplied for this earlier synthetic assertion."
                        }
                      }
                    },
                    "clocks": {
                      "effective_from": {
                        "precision": "unknown"
                      },
                      "effective_until": {
                        "precision": "unknown"
                      },
                      "source_published": {
                        "precision": "unknown"
                      },
                      "acquired": {
                        "precision": "instant",
                        "value": "2026-09-01T12:00:00Z"
                      },
                      "processed": {
                        "precision": "instant",
                        "value": "2026-09-01T12:10:00Z"
                      },
                      "verified": {
                        "precision": "unknown"
                      }
                    },
                    "evidence_path": "/v1/entities/00000001-1111-4111-8111-000000000001/evidence?manifest_id=00000002-1111-4111-8111-000000000002",
                    "limitations": [
                      "Synthetic fixture"
                    ],
                    "freshness": {
                      "state": "unknown",
                      "age_basis": "unknown",
                      "evaluated_at": "2026-09-07T10:00:00Z",
                      "policy_revision": "synthetic-freshness-1",
                      "age_min_seconds": null,
                      "age_max_seconds": null
                    }
                  }
                ],
                "modules": [],
                "limitations": [
                  "Not a real entity result"
                ],
                "confidence_summary": {
                  "state": "unavailable",
                  "method_revision": "sei-0.1",
                  "rating": {
                    "state": "not_assessed",
                    "score_basis_points": null,
                    "display_percent": null,
                    "zone": null,
                    "zone_label": "Not assessed",
                    "interpretation": "We do not have a usable basis to assess this information.",
                    "explanation": "No qualified SEI aggregate profile supplied.",
                    "meaning": "evidence_index_not_probability",
                    "method_revision": "sei-0.1",
                    "zone_policy_revision": "sez-0.1"
                  },
                  "reason": "assessment_unavailable",
                  "explanation": "This older synthetic result has no SEI aggregate basis; no percentage is inferred."
                },
                "completeness": "complete_permitted_projection",
                "projection_binding": {
                  "profile_id": "architecture-qualification-example-inactive",
                  "profile_revision": "1",
                  "slot_manifest_sha256": "a3c1747d93f81c16dcb00b5371c9bad6847feb5f39d2f33959ba3011ca4205ae",
                  "confidence_policy_revision": "sei-0.1"
                },
                "slot_outcomes": [
                  {
                    "slot_id": "identity.name",
                    "state": "provided",
                    "claim_ids": [
                      "00000003-1111-4111-8111-000000000003"
                    ]
                  }
                ]
              },
              "normalisation": {
                "policy_revision": "normalisation-0.1",
                "status": "not_assessed",
                "issues": [],
                "reference_versions": [],
                "raw_values_included": false
              },
              "identity_assessment": {
                "assessment_id": "90000000-0000-4000-8000-000000000002",
                "method_revision": "sli-0.1",
                "linkage_policy_revision": "synthetic-qualified-identifier-1",
                "evaluated_at": "2026-09-09T12:00:00Z",
                "rating": {
                  "state": "assessed",
                  "score_basis_points": 10000,
                  "display_percent": 100,
                  "zone": "strong",
                  "zone_label": "Strong support",
                  "interpretation": "The specified evidence checks provide strong support; remaining limitations stay visible.",
                  "explanation": "Stipulated exact issuer-scoped identifier with completed checks; no executed matching result.",
                  "meaning": "evidence_index_not_probability",
                  "method_revision": "sli-0.1",
                  "zone_policy_revision": "sez-0.1"
                },
                "explanation": {
                  "summary": "Stipulated synthetic qualified input binding.",
                  "reason_codes": [
                    "input_identity_strong"
                  ],
                  "limiting_factors": [
                    "Synthetic review example; not empirical evidence."
                  ],
                  "next_checks": [
                    "Qualify the applicable source and service profile before live use."
                  ],
                  "scope_statement": "This exact synthetic company, assertion and stated time only."
                },
                "calibration_status": "not_calibrated",
                "target": "input_reference_to_legal_entity",
                "qualification": "exact_checked_identifier"
              },
              "recovery": {
                "policy_revision": "recovery-0.1",
                "actions": [],
                "automatic_retry_allowed": false
              }
            },
            "receipt": {
              "receipt_id": "00000005-1111-4111-8111-000000000005",
              "operation_id": "00000006-1111-4111-8111-000000000006",
              "environment": "synthetic-review",
              "committed_at": "2026-09-07T10:00:00Z",
              "accepted_offer_id": "11111111-1111-4111-8111-111111111111",
              "original_period_id": "00000008-1111-4111-8111-000000000008",
              "subject_versions": [
                {
                  "entity_id": "00000001-1111-4111-8111-000000000001",
                  "environment": "synthetic-review",
                  "manifest_id": "00000002-1111-4111-8111-000000000002",
                  "subject_type": "legal_entity"
                }
              ],
              "profile_revision": "synthetic-review-1",
              "policy_revision": "synthetic-policy-1",
              "charged_units": "1",
              "unit": "synthetic_operation_unit",
              "unit_scale": 1,
              "settlement": "settled",
              "result_available_until": "2026-09-08T10:00:00Z",
              "receipt_available_until": "2026-09-14T10:00:00Z",
              "delivery_meaning": "authorised_delivery_commit_not_client_receipt",
              "projection": "full_permitted",
              "offer_binding": {
                "offer_id": "11111111-1111-4111-8111-111111111111",
                "offer_version": 1,
                "offer_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
                "policy_pins": {
                  "tariff": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "terms": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "credit": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "refresh": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "retrieval": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "eligibility": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "protection": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "rights": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "success": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  }
                },
                "agreement_id": "22222222-2222-4222-8222-222222222222",
                "agreement_revision": 1,
                "funded_period_id": "00000008-1111-4111-8111-000000000008",
                "selection_evidence_id": "22222222-2222-4222-8222-222222222222"
              },
              "classification_order_id": null,
              "classification_item_ids": []
            },
            "meta": {
              "request_id": "00000007-1111-4111-8111-000000000007",
              "served_at": "2026-09-07T10:00:00Z",
              "profile_revision": "synthetic-review-1",
              "synthetic": true,
              "replayed": false,
              "warnings": [
                "Illustration only; limits, retention and units are not approved production terms."
              ]
            }
          }
        }
      }
    },
    "400": {
      "description": "invalid_request",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "invalid_request"
                    ]
                  },
                  "status": {
                    "const": 400
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:invalid_request",
            "title": "Malformed JSON, duplicate keys, timestamp, header or structural input.",
            "status": 400,
            "code": "invalid_request",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "invalid_request"
      ]
    },
    "401": {
      "description": "unauthenticated",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "unauthenticated"
                    ]
                  },
                  "status": {
                    "const": 401
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:unauthenticated",
            "title": "Missing/invalid access token; no protected resource details.",
            "status": 401,
            "code": "unauthenticated",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "reauthenticate",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "unauthenticated"
      ]
    },
    "403": {
      "description": "permission_denied; entitlement_denied; authority_revoked",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "permission_denied",
                      "entitlement_denied",
                      "authority_revoked"
                    ]
                  },
                  "status": {
                    "const": 403
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:permission_denied",
            "title": "Authenticated principal lacks the action/resource grant.",
            "status": 403,
            "code": "permission_denied",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "permission_denied",
        "entitlement_denied",
        "authority_revoked"
      ]
    },
    "404": {
      "description": "resource_not_found",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "resource_not_found"
                    ]
                  },
                  "status": {
                    "const": 404
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:resource_not_found",
            "title": "Unknown resource, or tenant-private reference intentionally concealed.",
            "status": 404,
            "code": "resource_not_found",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "resource_not_found"
      ]
    },
    "409": {
      "description": "idempotency_conflict; operation_in_progress; result_invalidated",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "idempotency_conflict",
                      "operation_in_progress",
                      "result_invalidated"
                    ]
                  },
                  "status": {
                    "const": 409
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:idempotency_conflict",
            "title": "Same key with different canonical request or creation time.",
            "status": 409,
            "code": "idempotency_conflict",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": "00000006-1111-4111-8111-000000000006",
            "retry_action": "do_not_retry",
            "usage_state": "unchanged"
          }
        }
      },
      "x-error-codes": [
        "idempotency_conflict",
        "operation_in_progress",
        "result_invalidated"
      ]
    },
    "410": {
      "description": "operation_expired; result_expired",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "operation_expired",
                      "result_expired"
                    ]
                  },
                  "status": {
                    "const": 410
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:operation_expired",
            "title": "Old logical request outside retained/admission window; not newly charged.",
            "status": 410,
            "code": "operation_expired",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "unchanged",
            "status_path": null
          }
        }
      },
      "x-error-codes": [
        "operation_expired",
        "result_expired"
      ]
    },
    "413": {
      "description": "payload_too_large",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "payload_too_large"
                    ]
                  },
                  "status": {
                    "const": 413
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:payload_too_large",
            "title": "Body exceeds profile admission limit.",
            "status": 413,
            "code": "payload_too_large",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "payload_too_large"
      ]
    },
    "422": {
      "description": "unsupported_scope; invalid_identifier; limit_out_of_range",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "unsupported_scope",
                      "invalid_identifier",
                      "limit_out_of_range"
                    ]
                  },
                  "status": {
                    "const": 422
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:unsupported_scope",
            "title": "Well-formed territory/identifier/module/projection is not released in profile.",
            "status": 422,
            "code": "unsupported_scope",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "unsupported_scope",
        "invalid_identifier",
        "limit_out_of_range"
      ]
    },
    "429": {
      "description": "rate_limited; concurrency_limited; budget_exhausted",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "rate_limited",
                      "concurrency_limited",
                      "budget_exhausted"
                    ]
                  },
                  "status": {
                    "const": 429
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:rate_limited",
            "title": "Throughput admission refused.",
            "status": 429,
            "code": "rate_limited",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "wait_then_retry_same_operation",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "rate_limited",
        "concurrency_limited",
        "budget_exhausted"
      ]
    },
    "500": {
      "description": "internal_error",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "internal_error"
                    ]
                  },
                  "status": {
                    "const": 500
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:internal_error",
            "title": "Safe internal failure; no stack or protected payload.",
            "status": 500,
            "code": "internal_error",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "wait_then_retry_same_operation",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "internal_error"
      ]
    },
    "503": {
      "description": "dependency_unavailable; correction_pending; completion_uncertain",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "dependency_unavailable",
                      "correction_pending",
                      "completion_uncertain"
                    ]
                  },
                  "status": {
                    "const": 503
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:dependency_unavailable",
            "title": "Required policy, publication, ledger or search dependency unavailable.",
            "status": 503,
            "code": "dependency_unavailable",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "wait_then_retry_same_operation",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "dependency_unavailable",
        "correction_pending",
        "completion_uncertain"
      ]
    },
    "504": {
      "description": "operation_timeout",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "operation_timeout"
                    ]
                  },
                  "status": {
                    "const": 504
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:operation_timeout",
            "title": "Deadline exceeded; status determines final reservation/settlement.",
            "status": 504,
            "code": "operation_timeout",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": "00000006-1111-4111-8111-000000000006",
            "retry_action": "poll_operation",
            "usage_state": "uncertain",
            "status_path": "/v1/operations/00000006-1111-4111-8111-000000000006"
          }
        }
      },
      "x-error-codes": [
        "operation_timeout"
      ]
    },
    "default": {
      "description": "RFC 9457 problem; exact code/status/usage rules in errors.json. Current authority applies to all errors and replay.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Problem"
              },
              {
                "properties": {
                  "code": {
                    "enum": [
                      "invalid_request",
                      "unauthenticated",
                      "permission_denied",
                      "entitlement_denied",
                      "authority_revoked",
                      "resource_not_found",
                      "idempotency_conflict",
                      "operation_in_progress",
                      "result_invalidated",
                      "operation_expired",
                      "result_expired",
                      "payload_too_large",
                      "unsupported_scope",
                      "invalid_identifier",
                      "limit_out_of_range",
                      "rate_limited",
                      "concurrency_limited",
                      "budget_exhausted",
                      "dependency_unavailable",
                      "correction_pending",
                      "completion_uncertain",
                      "operation_timeout",
                      "internal_error"
                    ]
                  }
                }
              }
            ]
          }
        }
      }
    }
  },
  "x-permission": "entity.resolve",
  "x-billable": true,
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/IdentifierLookupRequest"
        },
        "example": {
          "identifier": {
            "scheme": "GB_CH",
            "authority": "COMPANIES_HOUSE",
            "jurisdiction": "GB",
            "value": "00000001",
            "subject_type": "legal_entity"
          },
          "search_scope": {
            "territories": [
              "GB"
            ]
          }
        }
      }
    }
  },
  "x-cross-adapter-bound": {
    "operation": "lookupIdentifier",
    "rule": "#/x-delivery-bound-contract",
    "before_settlement": true
  }
}

Referenced schemas

Includes schemas used by this operation and its shared or inherited parameters. Open a schema to follow its related definitions.

Shared parameter definitions
{
  "Cursor": {
    "name": "cursor",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Opaque signed cursor bound to query, organisation, environment, profile, rights and index/publication generation."
  },
  "IdempotencyKey": {
    "name": "Idempotency-Key",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics."
  },
  "Manifest": {
    "name": "manifest_id",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Manifest returned by identity/search. A compatibility-bound follow-on read, not unrestricted historical query. Current rights and retention apply."
  },
  "MaxUnits": {
    "name": "Entity-Max-Units",
    "in": "header",
    "required": false,
    "schema": {
      "$ref": "#/components/schemas/Units"
    },
    "description": "Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority."
  },
  "OperationCreated": {
    "name": "Entity-Operation-Created-At",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "date-time",
      "maxLength": 35
    },
    "description": "Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry."
  },
  "PageSize": {
    "name": "page_size",
    "in": "query",
    "required": false,
    "schema": {
      "type": "integer",
      "minimum": 1,
      "x-profile-maximum": "page_size_max"
    },
    "description": "Default and maximum from the active profile."
  },
  "ReceiptContext": {
    "name": "Entity-Receipt-Context",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Readable own-organisation receipt containing the requested entity/manifest. Binds follow-on evidence/module reads to a known permitted result within its retention window; this is not unrestricted historical access."
  },
  "ServiceProfile": {
    "name": "Entity-Service-Profile",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
  }
}
Inherited path parameters
[]

All API operations