{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/toku/json-schema/toku-beneficiary-response-schema.json",
  "title": "BeneficiaryResponse",
  "description": "Un Beneficiary: la persona o empresa que recibe un pago de la Organization.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/toku-beneficiaries-api-openapi.yml#/components/schemas/BeneficiaryResponse",
  "properties": {
    "country_code": {
      "description": "País del Beneficiary, en formato ISO.",
      "title": "Country Code",
      "type": "string"
    },
    "created_at": {
      "description": "Momento en que se creó el Beneficiary.",
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "created_by": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Correo del usuario de la webapp que creó el Beneficiary. Vacío cuando la carga vino de una integración por API key.",
      "title": "Created By"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Correo de contacto del Beneficiary.",
      "title": "Email"
    },
    "external_id": {
      "description": "Identificador del Beneficiary en el sistema de origen.",
      "title": "External Id",
      "type": "string"
    },
    "id_beneficiary": {
      "description": "Identificador del Beneficiary.",
      "title": "Id Beneficiary",
      "type": "string"
    },
    "id_beneficiary_batch": {
      "description": "Identificador del lote de carga en que se creó el Beneficiary.",
      "title": "Id Beneficiary Batch",
      "type": "string"
    },
    "identity_document": {
      "anyOf": [
        {
          "$ref": "#/$defs/IdentityDocument"
        },
        {
          "type": "null"
        }
      ],
      "description": "Documento de identidad tributaria del Beneficiary: RUT en Chile, y CURP, RFC o TAX_ID en México."
    },
    "metadata": {
      "additionalProperties": true,
      "description": "Datos libres que la Organization asocia al Beneficiary.",
      "title": "Metadata",
      "type": "object"
    },
    "name": {
      "description": "Nombre o razón social del Beneficiary.",
      "title": "Name",
      "type": "string"
    },
    "organization_id": {
      "description": "Identificador de la Organization dueña del Beneficiary.",
      "title": "Organization Id",
      "type": "string"
    },
    "phone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Teléfono de contacto del Beneficiary.",
      "title": "Phone"
    },
    "types": {
      "description": "Categorías con que la Organization clasifica al Beneficiary según la relación que tiene con él. Son etiquetas descriptivas: puede llevar varias y ninguna cambia cómo se le paga ni qué validaciones se le aplican.",
      "items": {
        "$ref": "#/$defs/BeneficiaryType"
      },
      "title": "Types",
      "type": "array"
    },
    "updated_at": {
      "description": "Momento de la última modificación del Beneficiary.",
      "format": "date-time",
      "title": "Updated At",
      "type": "string"
    }
  },
  "required": [
    "id_beneficiary",
    "id_beneficiary_batch",
    "organization_id",
    "external_id",
    "country_code",
    "types",
    "name",
    "created_at",
    "updated_at"
  ],
  "type": "object",
  "$defs": {
    "BeneficiaryType": {
      "description": "Categorías con que la Organization clasifica a un Beneficiary según la relación que tiene con él. Son etiquetas descriptivas: un Beneficiary puede llevar varias y ninguna cambia cómo se le paga ni qué validaciones se le aplican.",
      "enum": [
        "VENDOR",
        "INSURANCE_PARTY",
        "AGENT",
        "BORROWER",
        "EMPLOYEE"
      ],
      "title": "BeneficiaryType",
      "type": "string"
    },
    "IdentityDocument": {
      "properties": {
        "number": {
          "title": "Number",
          "type": "string"
        },
        "type": {
          "allOf": [
            {
              "$ref": "#/$defs/IdentityDocumentType"
            }
          ],
          "description": "Tipo de documento con el que se identifica al Beneficiary. Tiene que corresponder al `country_code`: Chile solo admite `RUT`; México admite `RFC`, el registro tributario, `CURP`, la clave de registro poblacional, y `TAX_ID`, el registro tributario genérico para un Beneficiary sin RFC. Si no corresponde, la solicitud se rechaza."
        }
      },
      "required": [
        "type",
        "number"
      ],
      "title": "IdentityDocument",
      "type": "object"
    },
    "IdentityDocumentType": {
      "description": "Tipos de documento con que se identifica a un Beneficiary. Cada uno corresponde a un país: `RUT` es el rol único tributario chileno y solo se acepta en Chile; `RFC` es el registro tributario mexicano, `CURP` la clave de registro poblacional y `TAX_ID` el registro tributario genérico para un Beneficiary sin RFC, y los tres solo se aceptan en México.",
      "enum": [
        "CURP",
        "RFC",
        "RUT",
        "TAX_ID"
      ],
      "title": "IdentityDocumentType",
      "type": "string"
    }
  }
}