Social Security

Service to query a person's social security information in Colombia. Returns personal information and the history of social security contributions.

POST /validate/social-security HTTP/1.1
HOST: {{api_auco}}
Authorization: {{private_key}}

info

This service uses the company's private key

Colombia Only

This service is only available for social security queries in Colombia. The accepted document types are Colombian Citizenship Card (CC) and Foreign ID Card (CE).

Name	Description
email String	Required. Email of the process creator. This email must be registered on the Auco platform and must belong to the company.
type String	Required. Identity document type. Accepted values: CC, CE
identification String	Required. Identity document number to query.

🧪 Usage examples

Curl

curl -X POST '{{api_auco}}/validate/social-security' \
  -H 'Authorization: {{private_key}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@company.com",
    "type": "CC",
    "identification": "123456781"
  }'

Python

import requests

response = requests.post(
  '{{api_auco}}/validate/social-security',
  headers={
    'Authorization': '{{private_key}}',
    'Content-Type': 'application/json'
  },
  json={
    "email": "user@company.com",
    "type": "CC",
    "identification": "123456781"
  }
)
print(response.json())

Node.js

const axios = require('axios');

axios.post('{{api_auco}}/validate/social-security', {
  email: 'user@company.com',
  type: 'CC',
  identification: '123456781'
}, {
  headers: {
    Authorization: '{{private_key}}',
    'Content-Type': 'application/json'
  }
})
.then((response) => console.log(response.data));

📥 Response structure

Main fields

Field	Type	Description
code	String	Unique code of the generated validation
documentType	String	Queried document type
documentNumber	String	Queried document number
personalInfo	Object	Personal information of the holder
contributionPeriods	Array	List of social security contribution periods

personalInfo object

Field	Type	Description
firstName	String	First name
middleName	String	Middle name
lastName	String	Last name
secondLastName	String	Second last name

contributionPeriods[] object

Field	Type	Description
period	String	Contribution period in YYYYMM format
baseIncome	Number	Contribution base income in COP
employer	Object	Employer or contributor information
contributorType	Object	Contributor type
monthsWithEmployer	Number	Accumulated months with the employer
hasChange	Boolean	Indicates if there was an employer change in this period
lastChangeDate	String	Date of last employer change (YYYYMM or null)

employer object

Field	Type	Description
name	String	Name or company name of the employer
documentType	String	Document type (NI = Tax ID, CC = ID Card)
documentNumber	String	Employer's document number

contributorType object

Field	Type	Description
code	String	Contributor type code
description	String	Contributor type description

Common contributor types

Code	Description
1	Employee (Dependent)
3	Independent
57	Voluntary Independent to Occupational Risk System
59	Independent with service contract greater than 1 month

📥 Response examples

200: Successful query

{
  "code": "VAL1234ABC",
  "documentType": "CC",
  "documentNumber": "1000000001",
  "personalInfo": {
    "firstName": "JUAN",
    "middleName": "CARLOS",
    "lastName": "GARCIA",
    "secondLastName": "MARTINEZ"
  },
  "contributionPeriods": [
    {
      "period": "202501",
      "baseIncome": 3000000,
      "employer": {
        "name": "EMPRESA EJEMPLO SAS",
        "documentType": "NI",
        "documentNumber": "900123456"
      },
      "contributorType": {
        "code": "1",
        "description": "Dependiente"
      },
      "monthsWithEmployer": 18,
      "hasChange": false,
      "lastChangeDate": null
    }
  ]
}

400: User not found

{
  "message": "USER_NOTFOUND"
}

400: Document not found

{
  "message": "SOCIAL_SECURITY_NOT_FOUND"
}

400: Service unavailable

{
  "message": "SOCIAL_SECURITY_SERVICE_ERROR"
}

⚠️ Error responses

Code	Message	Description
400	USER_NOTFOUND	Email does not exist in the company.
400	SOCIAL_SECURITY_NOT_FOUND	No social security information found for the document.
400	SOCIAL_SECURITY_SERVICE_ERROR	The social security service is temporarily unavailable.
401	-	Invalid or missing authentication.

🧪 Test data (Development environment)

For testing in the development environment, you can use the following documents:

Document	Type	Description
1000000001	CC	Dependent employee with stable history
1000000002	CC	Independent changing to dependent
1000000003	CC	Multiple employer changes

ℹ️ Additional notes

• The service returns the contribution history for approximately the last 12 months.
• The same period may have multiple records if the person has several employers or simultaneous contribution types.
• The hasChange field indicates if there was an employer change in that specific period.
• The monthsWithEmployer field represents the accumulated tenure with that specific employer.
• The email must correspond to an active user of the company.