{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bynn-com/json-schema/bynn-com-bynn-v1-entities-dossier-entity-schema.json",
  "title": "Bynn_V1_Entities_DossierEntity",
  "description": "Bynn_V1_Entities_DossierEntity model",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bynn-com-openapi.json#/components/schemas/Bynn_V1_Entities_DossierEntity",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Dossier identifier (prefixed)."
    },
    "token": {
      "type": "string",
      "description": "Humanized dossier token."
    },
    "type": {
      "type": "string",
      "enum": [
        "not_specified",
        "kyc",
        "kyb",
        "doc"
      ],
      "description": "Dossier type."
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "open",
        "completed",
        "archived",
        "closed",
        "needs_attention",
        "approved",
        "rejected"
      ],
      "description": "Business status of the dossier."
    },
    "name": {
      "type": "string",
      "description": "Dossier / applicant name."
    },
    "name_latin": {
      "type": "string",
      "description": "Latin-transliterated name, when applicable."
    },
    "reference": {
      "type": "string",
      "description": "Your customer reference (customer_identification)."
    },
    "description": {
      "type": "string",
      "description": "Free-text description, when set."
    },
    "risk_score": {
      "type": "integer",
      "format": "int32",
      "description": "Dossier risk score (0-100)."
    },
    "is_test": {
      "type": "boolean",
      "description": "Whether this dossier was created with a test/sandbox key."
    },
    "download_status": {
      "type": "string",
      "enum": [
        "not_downloaded",
        "downloaded",
        "synced"
      ],
      "description": "Download status."
    },
    "workflow_status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "completed",
        "failed",
        "awaiting_approval"
      ],
      "description": "Workflow status (autodoc dossiers)."
    },
    "level": {
      "type": "object",
      "description": "The verification level the dossier runs under."
    },
    "documents_count": {
      "type": "integer",
      "format": "int32",
      "description": "Number of documents collected."
    },
    "documents_required": {
      "type": "integer",
      "format": "int32",
      "description": "Number of documents expected."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {}
      },
      "description": "User-editable organization tags on the dossier."
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 creation timestamp."
    },
    "updated_at": {
      "type": "string",
      "description": "ISO 8601 last-update timestamp."
    },
    "completed_at": {
      "type": "string",
      "description": "ISO 8601 completion timestamp, when completed."
    },
    "media": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Bynn_V1_Entities_MediumEntity"
      },
      "description": "All dossier-level media assets, each with type and a short-lived URL (~5 min — download immediately)."
    },
    "entities": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Bynn_V1_Entities_DossierApplicantEntity"
      },
      "description": "Applicants (subjects) on the dossier with their personal info, identity documents, media and liveness images."
    }
  },
  "required": [
    "id",
    "token",
    "type",
    "status",
    "name",
    "name_latin",
    "reference",
    "description",
    "risk_score",
    "is_test",
    "download_status",
    "workflow_status",
    "level",
    "documents_count",
    "documents_required",
    "tags",
    "created_at",
    "updated_at",
    "completed_at",
    "media",
    "entities"
  ],
  "$defs": {
    "Bynn_V1_Entities_DossierApplicantEntity": {
      "type": "object",
      "properties": {
        "token": {
          "type": "string",
          "description": "Applicant (entity) identifier."
        },
        "name": {
          "type": "string",
          "description": "Full name of the applicant."
        },
        "name_latin": {
          "type": "string",
          "description": "Latin-transliterated name, when the original is non-Latin."
        },
        "first_name": {
          "type": "string",
          "description": "Given name."
        },
        "last_name": {
          "type": "string",
          "description": "Surname."
        },
        "date_of_birth": {
          "type": "string",
          "description": "Date of birth (YYYY-MM-DD)."
        },
        "gender": {
          "type": "string",
          "enum": [
            "female",
            "male"
          ],
          "description": "Gender."
        },
        "personal_number": {
          "type": "string",
          "description": "National / personal identification number, when captured."
        },
        "nationality": {
          "type": "string",
          "description": "Nationality country."
        },
        "residence_country": {
          "type": "string",
          "description": "Country of residence."
        },
        "birth_country": {
          "type": "string",
          "description": "Country of birth."
        },
        "email": {
          "type": "string",
          "description": "Applicant email address."
        },
        "phone_number": {
          "type": "string",
          "description": "Applicant phone number."
        },
        "occupation": {
          "type": "string",
          "description": "Occupation, when captured."
        },
        "marital_status": {
          "type": "string",
          "description": "Marital status, when captured."
        },
        "height_cm": {
          "type": "integer",
          "format": "int32",
          "description": "Height in centimetres, when read from a document."
        },
        "risk_score": {
          "type": "integer",
          "format": "int32",
          "description": "Applicant risk score (0-100)."
        },
        "address": {
          "type": "object",
          "description": "Applicant address, as captured."
        },
        "liveness_status": {
          "type": "string",
          "enum": [
            "not_verified",
            "pre_verification_successful",
            "successful",
            "failed",
            "skipped"
          ],
          "description": "Liveness verification outcome."
        },
        "liveness_confidence": {
          "type": "number",
          "description": "Liveness confidence score."
        },
        "liveness_images": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {}
          },
          "description": "All captured liveness selfie frames as { url, bounding_box }. URLs are short-lived presigned links (~5 min) — download immediately."
        },
        "identity_documents": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Bynn_V1_Entities_IdentityDocumentEntity"
          },
          "description": "Identity documents captured for this applicant."
        },
        "media": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Bynn_V1_Entities_MediumEntity"
          },
          "description": "All media assets for this applicant, each with type and a short-lived URL."
        }
      },
      "required": [
        "token",
        "name",
        "name_latin",
        "first_name",
        "last_name",
        "date_of_birth",
        "gender",
        "personal_number",
        "nationality",
        "residence_country",
        "birth_country",
        "email",
        "phone_number",
        "occupation",
        "marital_status",
        "height_cm",
        "risk_score",
        "address",
        "liveness_status",
        "liveness_confidence",
        "liveness_images",
        "identity_documents",
        "media"
      ]
    },
    "Bynn_V1_Entities_IdentityDocumentEntity": {
      "type": "object",
      "properties": {
        "token": {
          "type": "string",
          "description": "Identity document identifier."
        },
        "document_type": {
          "type": "string",
          "enum": [
            "passport",
            "identity_card",
            "drivers_license",
            "residence_permit",
            "social_security",
            "unknown"
          ],
          "description": "Detected document category."
        },
        "document_number": {
          "type": "string",
          "description": "Document number as printed on the document."
        },
        "first_name": {
          "type": "string",
          "description": "Given name as read from the document."
        },
        "last_name": {
          "type": "string",
          "description": "Surname as read from the document."
        },
        "full_name": {
          "type": "string",
          "description": "Full name as read from the document."
        },
        "name_latin": {
          "type": "string",
          "description": "Latin-transliterated full name, when the original is non-Latin."
        },
        "birth_date": {
          "type": "string",
          "description": "Date of birth (YYYY-MM-DD)."
        },
        "issue_date": {
          "type": "string",
          "description": "Issue date (YYYY-MM-DD)."
        },
        "expiry_date": {
          "type": "string",
          "description": "Expiry date (YYYY-MM-DD)."
        },
        "is_expired": {
          "type": "boolean",
          "description": "Whether the document is past its expiry date."
        },
        "gender": {
          "type": "string",
          "enum": [
            "female",
            "male",
            "intersex",
            "not_specified"
          ],
          "description": "Gender as read from the document."
        },
        "nationality_code": {
          "type": "string",
          "description": "Nationality as an ISO country code from the document."
        },
        "issuing_country": {
          "type": "string",
          "description": "Country that issued the document."
        },
        "personal_number": {
          "type": "string",
          "description": "National / personal identification number, when present."
        },
        "place_of_birth": {
          "type": "string",
          "description": "Place of birth, when present."
        },
        "document_status": {
          "type": "string",
          "description": "Reported status of the document."
        },
        "mrz_type": {
          "type": "string",
          "description": "Machine Readable Zone format (e.g. TD1, TD3)."
        },
        "mrz_checksum_valid": {
          "type": "boolean",
          "description": "Whether the MRZ checksums validated."
        },
        "has_portrait_image": {
          "type": "boolean",
          "description": "Whether a portrait photo was detected on the document."
        },
        "has_signature": {
          "type": "boolean",
          "description": "Whether a signature was detected on the document."
        },
        "tampered": {
          "type": "boolean",
          "description": "Whether tampering was detected."
        },
        "e_id": {
          "type": "boolean",
          "description": "Whether NFC / electronic-chip (eID) data was read from the document."
        },
        "risk_score": {
          "type": "integer",
          "format": "int32",
          "description": "Document risk score (0-100)."
        },
        "verification_status": {
          "type": "string",
          "enum": [
            "pending",
            "analyzed",
            "verified",
            "rejected",
            "expired",
            "requires_resubmission"
          ],
          "description": "Verification outcome for the document."
        },
        "images": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {}
          },
          "description": "Captured document images (front / back / cropped) with type and URL."
        }
      },
      "required": [
        "token",
        "document_type",
        "document_number",
        "first_name",
        "last_name",
        "full_name",
        "name_latin",
        "birth_date",
        "issue_date",
        "expiry_date",
        "is_expired",
        "gender",
        "nationality_code",
        "issuing_country",
        "personal_number",
        "place_of_birth",
        "document_status",
        "mrz_type",
        "mrz_checksum_valid",
        "has_portrait_image",
        "has_signature",
        "tampered",
        "e_id",
        "risk_score",
        "verification_status",
        "images"
      ]
    },
    "Bynn_V1_Entities_MediumEntity": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "The kind of media asset (e.g. passport_front_image, selfie_image, extracted_avatar, dossier_report)."
        },
        "name": {
          "type": "string",
          "description": "Original file name of the media asset."
        },
        "page": {
          "type": "integer",
          "format": "int32",
          "description": "Page number for multi-page documents (starts at 1)."
        },
        "url": {
          "type": "string",
          "description": "Signed, time-limited URL to download the file. Nil when no file is attached."
        },
        "created_at": {
          "type": "string",
          "description": "ISO 8601 creation timestamp."
        }
      },
      "required": [
        "type",
        "name",
        "page",
        "url",
        "created_at"
      ]
    }
  }
}