Insert Persons

Time	Status	User Agent
Retrieving recent requests…

Crea una o más personas con los campos adicionales de la versión 2 y obtén el person_id para vincular cuentas comitentes.

Antes de empezar

Reuní los códigos de catálogos que correspondan, como actividad AFIP, país, tipo de documento, estado civil, etc..
Armá el arreglo persons con entre 1 y 10 registros.
Incluí human_person para una persona humana o legal_person para una persona jurídica.
Si is_pep es true, completá también pep_relation y pep_position.
Guardá el person_id de la respuesta para usarlo al crear una cuenta comitente.

Qué cambia en `v2`

Esta versión agrega campos para registrar información PEP (persona expuesta políticamente), FATCA (obligaciones fiscales vinculadas con Estados Unidos) y OECD (identificadores fiscales de países que participan en el intercambio automático de información).

Qué envía este endpoint

El body acepta un objeto array de objetos persons.

Campo	Tipo	Requerido	Restricciones	Descripción
`persons`	array de objetos	Sí	mínimo `1`, máximo `10`	Lista de personas a crear en una sola solicitud.

Estructura de cada objeto `person`

Campo	Tipo	Requerido	Descripción
`job_activity_id`	integer	Sí	Código de actividad AFIP.
`country_document_id`	string	Sí	Código de país del documento.
`nationality_id`	string	Sí	Código de país de nacionalidad.
`is_aml_cft_subject`	boolean	Sí	Indica si la persona es sujeto obligado.
`is_pep`	boolean	Sí	Indica si la persona es políticamente expuesta.
`pep_relation`	string	No	Es necesario cuando `is_pep` es `true`. Relación de la persona con el riesgo político. Ejemplo: `direct`.
`pep_position`	string	No	Es necesario cuando `is_pep` es `true`. Cargo o posición si es PEP. Ejemplo: `ministro de finanzas`.
`fatca_id`	string	No	Identificador FATCA si la persona está registrada o tiene operaciones en Estados Unidos.
`oecd_identifiers`	array de objetos	No	Lista de identificadores fiscales en países OCDE.
`tax_identifications`	object	Sí	Datos impositivos de la persona.
`domiciles`	array de objetos	Sí	Domicilios asociados a la persona.
`contact`	object	Sí	Datos de contacto.
`human_person`	object	No	Datos de persona humana. Incluilo cuando des de alta una persona física.
`legal_person`	object	No	Datos de persona jurídica. Incluilo cuando des de alta una persona jurídica.

Reglas para PEP, FATCA y OECD

Si is_pep es true, enviá pep_relation y pep_position.
Si is_pep es false, podés omitir pep_relation y pep_position o enviarlos vacíos.
Si la persona no tiene registro u operaciones alcanzadas por FATCA, podés enviar fatca_id vacío.
Si la persona no tiene identificadores fiscales en países OCDE, enviá oecd_identifiers como un arreglo vacío.

Objeto `oecd_identifiers`

Cada elemento del arreglo oecd_identifiers representa un identificador fiscal asociado a un país miembro de la OCDE.

Campo	Tipo	Requerido	Descripción
`oecd_identifier`	string	Sí	Identificador fiscal en el país informado.
`country_id`	string	Sí	Código del país miembro de la OCDE.

Objeto `tax_identifications`

Campo	Tipo	Requerido	Restricciones	Descripción
`tax_identification_value`	string	Sí	longitud exacta `11`	CUIT, CUIL o CDI.
`residence_country_id`	string	Sí	—	Código de país de residencia.
`tax_identification_type_id`	string	Sí	—	Tipo de identificación tributaria.
`taxpayer_income_tax_type_id`	string	Sí	—	Tipo de contribuyente de impuesto a las ganancias o ingresos.
`vat_taxpayer_type_id`	string	Sí	—	Tipo de contribuyente IVA.
`vat_country_taxpayer_type_id`	string	Sí	—	País donde tributa IVA.

Objeto `human_person`

Campo	Tipo	Requerido	Restricciones	Descripción
`surname`	string	Sí	—	Apellido.
`name`	string	Sí	—	Nombre.
`document_type_id`	string	Sí	—	Tipo de documento.
`document_num`	string	Sí	mínimo `7` caracteres	Número de documento.
`civil_status_id`	string	Sí	—	Estado civil.
`birth_date`	string	Sí	formato `date`	Fecha de nacimiento.
`birth_place`	string	Sí	—	Lugar de nacimiento.
`gender_id`	string	Sí	máximo `1` carácter	Género.
`signature`	string	Sí	base64 PNG	Si bien el campo es requerido, se puede enviar con un string vacío. Firma en PNG con transparencia.

Objeto `legal_person`

Campo	Tipo	Requerido	Descripción
`company_name`	string	Sí	Razón social.
`registration_number`	string	Sí	Número de inscripción.
`incorporation_place`	string	Sí	Lugar de constitución.
`country_id`	string	Sí	Código de país.
`constitution_date`	string	Sí	Fecha de constitución.
`book`	string	Sí	Libro.
`volume`	string	Sí	Tomo o volumen.
`page`	string	Sí	Folio o página.
`is_state_supplier`	boolean	Sí	Indica si es proveedora del Estado.
`corporate_type`	integer	Sí	Tipo societario.

Objeto `domiciles`

Cada elemento del arreglo domiciles representa un domicilio.

Campo	Tipo	Requerido	Descripción
`domicile_type_id`	string	Sí	Tipo de domicilio.
`house_number`	integer	Sí	Altura de la calle.
`street`	string	Sí	Calle.
`floor`	integer	No	Piso.
`apartment`	string	No	Departamento.
`country_id`	string	Sí	Código de país.
`province_id`	string	Sí	Código de provincia.
`zip_code`	integer	Sí	Código postal.
`location_id`	integer	Sí	Localidad.

Objeto `contact`

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Correo electrónico.
`mobile_phone`	string	Sí	Teléfono móvil en formato E.164.

Ejemplo: persona humana en `v2`

{
  "persons": [
    {
      "job_activity_id": 12112,
      "nationality_id": "ARG",
      "country_document_id": "ARG",
      "is_pep": true,
      "pep_relation": "direct",
      "pep_position": "Presidente",
      "is_aml_cft_subject": false,
      "fatca_id": "",
      "oecd_identifiers": [],
      "tax_identifications": {
        "tax_identification_value": "20341111111",
        "residence_country_id": "ARG",
        "tax_identification_type_id": "CUIT",
        "taxpayer_income_tax_type_id": "NOINS",
        "vat_taxpayer_type_id": "RM",
        "vat_country_taxpayer_type_id": "ARG"
      },
      "human_person": {
        "surname": "Doe",
        "name": "Jane",
        "document_type_id": "CUIL",
        "document_num": "34111112",
        "civil_status_id": "SOL",
        "birth_date": "2022-12-15",
        "birth_place": "ARG",
        "gender_id": "M",
        "signature": "<base64_png>"
      },
      "domiciles": [
        {
          "domicile_type_id": "PA",
          "house_number": 121,
          "street": "9 de Julio",
          "floor": 7,
          "apartment": "C",
          "country_id": "ARG",
          "province_id": "AR-B",
          "zip_code": 2324,
          "location_id": 1
        }
      ],
      "contact": {
        "email": "[email protected]",
        "mobile_phone": "+541112345678"
      }
    }
  ]
}

Ejemplo: persona jurídica en `v2`

{
  "persons": [
    {
      "job_activity_id": 12112,
      "nationality_id": "ARG",
      "country_document_id": "ARG",
      "is_pep": false,
      "is_aml_cft_subject": false,
      "fatca_id": "",
      "oecd_identifiers": [],
      "tax_identifications": {
        "tax_identification_value": "30712345678",
        "residence_country_id": "ARG",
        "tax_identification_type_id": "CUIT",
        "taxpayer_income_tax_type_id": "NOINS",
        "vat_taxpayer_type_id": "RM",
        "vat_country_taxpayer_type_id": "ARG"
      },
      "legal_person": {
        "company_name": "Mi Empresa S.R.L.",
        "registration_number": "A-1233445-Q",
        "incorporation_place": "Buenos Aires, Argentina",
        "country_id": "ARG",
        "constitution_date": "2024-01-10",
        "book": "12",
        "volume": "4",
        "page": "102",
        "is_state_supplier": false,
        "corporate_type": 1
      },
      "domiciles": [
        {
          "domicile_type_id": "PA",
          "house_number": 121,
          "street": "9 de Julio",
          "floor": 7,
          "apartment": "C",
          "country_id": "ARG",
          "province_id": "AR-B",
          "zip_code": 2324,
          "location_id": 1
        }
      ],
      "contact": {
        "email": "[email protected]",
        "mobile_phone": "+541112345678"
      }
    }
  ]
}

Respuesta esperada

La respuesta devuelve un arreglo items. Cada elemento incluye el resultado de una persona procesada.

{
  "items": [
    {
      "person_id": "F-8d567d64-3043-47de-8aa8-5d1d39f56c9e",
      "name": "Juan",
      "surname": "Perez",
      "tax_identification_value": "20341111111",
      "error": null
    },
    {
      "person_id": "J-8d567d64-3043-47de-8aa8-5d1d39f56c9e",
      "company_name": "Mi Empresa S.R.L.",
      "tax_identification_value": "30712345678",
      "error": null
    }
  ]
}

Si una alta falla, error incluye error_code y message para ese registro.

Errores frecuentes

422 Validation Error: revisá tipos, campos obligatorios y formatos como birth_date, email o mobile_phone.
tax_identification_value_already_exists: el CUIT, CUIL o CDI ya fue registrado.
Errores de catálogos, como invalid_country_id, invalid_document_type, invalid_civil_status o invalid_location_id: verificá que los códigos enviados existan en las tablas maestras de tu integración.
Errores de firma, como wrong_format_signature, wrong_aspect_ratio_signature, too_large_signature o signature_without_transparency: revisá el archivo PNG codificado en base64 antes de reenviar la solicitud.

Siguiente paso

Después de crear la persona, usá el person_id devuelto para crear una cuenta comitente con POST /api/accounts/v2/investment-accounts.

Antes de empezar

Qué cambia en v2

Qué envía este endpoint

Estructura de cada objeto person

Reglas para PEP, FATCA y OECD

Objeto oecd_identifiers

Objeto tax_identifications

Objeto human_person

Objeto legal_person

Objeto domiciles

Objeto contact

Ejemplo: persona humana en v2

Ejemplo: persona jurídica en v2