Social Security
Queries
Company data

Company data in RED System

⚠️

Add test=1 to run tests without real effects. In production, omit this parameter.

Queries the data of a company in the RED System (AER61 transaction) and, optionally, its situation (ACR69 transaction: CCC status, workers, CNAE, mutual insurance and collection). It is a read-only query. The company is searched by its cif.

The identification data (identificativos) is always returned; the other blocks are requested with options.

Parameters

  • test (number (1)) : For testing, add the test=1 parameter. It must be omitted in production. Returns sample data without querying the TGSS.
  • cif (string) : Company CIF (up to 10 characters). Mandatory.
  • ccc (integer) : Contribution account code (11 digits). Mandatory.
  • regimen (integer) : Scheme (4 digits). Mandatory.
  • options optional (array) : Blocks to return, in addition to identificativos (always included). Case-insensitive. Possible values:
    • constitucion: adds data.constitucion (incorporation and commercial registry entry).
    • domicilio: adds data.domicilio.
    • contacto: adds data.contacto (phones and email).
    • representantes: adds data.representantes (linked persons).
    • cnae: adds data.cnae with the first two digits of the current CNAE. Uses ccc and regimen.
    • situacion: adds data.situacion with the full CCC situation (see below). Uses ccc and regimen. If options is omitted or empty, constitucion, domicilio, contacto and representantes are returned. If only cnae and/or situacion are given, identificativos plus those blocks are returned. Requesting cnae and situacion together queries the situation only once.
GET /enterprise/data
{
    "test": 1,
    "cif": "B00000000",
    "ccc": "28000000001",
    "regimen": "0111",
    "options": [
        "constitucion",
        "domicilio",
        "contacto",
        "representantes",
        "cnae",
        "situacion"
    ]
}

Successful response

Respuesta
{
    "success": true,
    "message": "OK",
    "status": 200,
    "data": {
        "identificativos": {
            "net": "1234567",
            "nif": {
                "tipo": "9",
                "numero": "0B00000000"
            },
            "nacionalidad": {
                "codigo": "724",
                "descripcion": "ESPAÑA"
            },
            "razon_social": "EMPRESA DE PRUEBA SL",
            "forma_juridica": {
                "tipo": "B",
                "tipo_descripcion": "SOCIEDAD DE RESPONSA",
                "subtipo": "001",
                "subtipo_descripcion": "SOCIEDAD DE RESPONSABILI"
            },
            "objeto_social": {
                "codigo": "1",
                "descripcion": "ACTIVID.PROFESIONALES O EMPRESARIALES"
            },
            "fecha_inclusion_bd": "2018-03-01",
            "fecha_inscripcion_ss": "2018-03-08",
            "fecha_inicio_actividad": "2018-03-08",
            "fecha_extincion": null
        },
        "constitucion": {
            "sociedad_regular": "SI",
            "fecha_constitucion": "2018-02-20",
            "fecha_inscripcion_registro": "2018-02-27",
            "tipo_registro": "01",
            "provincia": {
                "codigo": "28",
                "descripcion": "MADRID"
            },
            "registro_mercantil": {
                "numero": "028",
                "tomo": "00123",
                "libro": "",
                "folio": "045",
                "seccion": "",
                "hoja": "123456"
            },
            "anotacion": {
                "codigo": "1",
                "descripcion": "INSCRIPCION"
            },
            "numero_otros_registros": ""
        },
        "domicilio": {
            "tipo_via": "CL",
            "nombre_via": "CALLE DE EJEMPLO",
            "numero": "00001",
            "bis": "",
            "bloque": "",
            "escalera": "",
            "piso": "",
            "puerta": "",
            "codigo_postal": "28001",
            "localidad": {
                "codigo": "28079",
                "descripcion": "MADRID"
            }
        },
        "contacto": [
            {
                "telefono_movil": {
                    "prefijo": "34",
                    "numero": "600000000"
                },
                "email": "CONTACTO@EJEMPLO.ES"
            }
        ],
        "representantes": [
            {
                "identity": "1",
                "nif": "00000000T",
                "nombre": "NOMBRE APELLIDO1 APELLIDO2",
                "fecha_vinculo_desde": "2018-03-08",
                "fecha_vinculo_hasta": null,
                "vin": "001",
                "sit": "VIG"
            }
        ],
        "situacion": {
            "regimen": "0111",
            "ccc": "28000000001",
            "ccc_principal": null,
            "razon_social": "EMPRESA DE PRUEBA SL",
            "net": "1234567",
            "id_empresario": {
                "tipo": "CIF",
                "documento": "B00000000"
            },
            "nss": {
                "provincia": "28",
                "numero": "00000000"
            },
            "ccc_anterior": null,
            "ccc_sucesor": null,
            "situacion": {
                "codigo": "1",
                "descripcion": "ALTA",
                "fecha_situacion": "2018-03-08",
                "fecha_alta_inicial": "2018-03-08"
            },
            "trabajadores": {
                "alta": 5,
                "fecha_alta_primer_trabajador": "2018-03-08",
                "ultima_baja_efecto_cotizacion": null
            },
            "colectivo": {
                "codigo": "000",
                "descripcion": "GENERAL"
            },
            "cnae": {
                "cnae93": "",
                "cnae09": {
                    "codigo": "6201",
                    "descripcion": "ACTIVIDADES DE PROGRAMACION INFORMATICA"
                },
                "cnae25": {
                    "codigo": "",
                    "descripcion": ""
                }
            },
            "cnae_two_digits": "62",
            "ta2": {
                "dias_alta": 5,
                "dias_baja": 0
            },
            "tipos_at_ep_it": {
                "iim": "0,65",
                "ims": "0,35",
                "total": "1,00"
            },
            "mutua": {
                "entidad_at_ep": {
                    "codigo": "151",
                    "nombre": "MUTUA DE PRUEBA",
                    "fecha": "2018-03-08",
                    "mes_vencimiento": "Marzo"
                },
                "mutua_it_cc": {
                    "opcion": "SI",
                    "fecha_opcion": "MAR/2018"
                }
            },
            "recaudacion": {
                "modo_pago": {
                    "codigo": "0",
                    "descripcion": "NORMAL"
                },
                "ingreso_diferido_anticipado": "0 meses",
                "deduccion_diferida_it": "NO AUTORIZADO",
                "pago_directo_it": "NO"
            }
        },
        "cnae": "62"
    }
}

situacion block

  • regimen, ccc, razon_social, net, id_empresario (tipo, documento) and nss (provincia, numero): identification of the queried CCC.
  • ccc_principal, ccc_anterior and ccc_sucesor: main CCC of the company and previous / successor CCC (provincia, numero, regimen and, for the last two, descripcion). They are null when they do not apply.
  • situacion: codigo, descripcion, fecha_situacion and fecha_alta_inicial (YYYY-MM-DD).
  • trabajadores: alta (number of registered workers), fecha_alta_primer_trabajador and ultima_baja_efecto_cotizacion.
  • colectivo: codigo and descripcion.
  • cnae: cnae93 and, for cnae09 and cnae25, codigo and descripcion. cnae_two_digits are the first two digits of the most recent CNAE available.
  • ta2: dias_alta and dias_baja. tipos_at_ep_it: iim, ims and total.
  • mutua: entidad_at_ep (codigo, nombre, fecha, mes_vencimiento) and mutua_it_cc (opcion, fecha_opcion).
  • recaudacion: modo_pago (codigo, descripcion), ingreso_diferido_anticipado, deduccion_diferida_it and pago_directo_it.

mutua and recaudacion come from a second TGSS screen (Collection). If the TGSS does not return it, the response is still successful but those two blocks are absent. Likewise, if the situation query fails, the response contains the identification data and the other requested blocks, with success: true and without situacion or cnae.

For backward compatibility, when cnae is requested and the TGSS returns the CNAE, the response also includes data.situacion.

Errors

Response status 422 (validation)

A mandatory parameter (cif, ccc, regimen) is missing or has an invalid format (ccc 11 digits, regimen 4 digits).

Respuesta
{
    "success": false,
    "message": "validation_errors",
    "status": 422,
    "data": [],
    "errors": {
        "ccc": [
            "El campo CCC es obligatorio cuando se pide la opción situacion."
        ],
        "regimen": [
            "El campo régimen es obligatorio cuando se pide la opción situacion."
        ]
    }
}

Response status 404 (company not found)

The TGSS returns no data for the given company. It is a final answer: there is no need to retry.

Respuesta
{
    "success": false,
    "message": "SISTEMA RED: Datos no encontrados.",
    "status": 404,
    "errors": {
        "tgss": [
            "SISTEMA RED: Datos no encontrados."
        ]
    }
}