Skip to main content

Colombia — Cédula barcode (PDF417)

Read the PDF417 barcode printed on the reverse of a Colombian cédula de ciudadanía (CC). Use this endpoint when you already have a capture of the back of the card and want machine-readable identity fields from the barcode, with optional fuzzy matching against values you collected elsewhere (OCR, user input, or a prior /v2/co/cedula lookup).

This is not a Registraduría or Procuraduría identity lookup. For official name resolution by document number, use Colombian Citizen (GET/POST /v2/co/cedula). For barcode validation inside SmartScan flows, see Scan Agent — Colombian barcode.

Anti-Fraud & Document Alteration Detection

This endpoint is specifically engineered as a critical anti-fraud mechanism. In real-world fraud scenarios, bad actors commonly modify the printed text or photo on the front of a cédula, but are unable to forge the proprietary 2D PDF417 barcode on the back. Cross-checking the barcode against front OCR exposes physical tampering immediately (verdict: "mismatch"). Furthermore, any attempt to tamper with or smudge the barcode itself breaks its Reed-Solomon error correction codewords, causing the read to fail completely (verdict: "unreadable").

Endpoint​

POST https://api.verifik.co/v2/co/cedula/barcode

Same path on the app host: POST https://verifik.app/v2/co/cedula/barcode.

Headers​

NameValue
Content-Typeapplication/json
AuthorizationBearer <token>

Parameters​

NameTypeRequiredDescription
backImagestringYesRear of the cédula as base64 (with or without a data: prefix) or a public HTTPS URL to the image. The barcode must be visible and in focus.
documentTypestringNoDocument type. Defaults to CC.
documentNumberstringNoCross-check: NUIP / document number to compare against the barcode payload.
firstNamestringNoCross-check: first name(s) to compare.
lastNamestringNoCross-check: last name(s) to compare.
genderstringNoCross-check: gender code or label to compare.
dateOfBirthstringNoCross-check: date of birth to compare (use the same format you store for the person, e.g. DD/MM/YYYY).
bloodTypestringNoCross-check: blood type to compare.
crossCheckobjectNoAlternative to top-level cross-check fields. Same keys: documentNumber, firstName, lastName, gender, dateOfBirth, bloodType. If both are sent, the API merges them with explicit body fields taking precedence.
barcodeReadAttemptsnumberNoOptional cap on internal read attempts when the image is difficult (glare, blur). When omitted, the service uses its default retry budget.

Decode-only: send only backImage (and optional documentType). The response data.verdict is decoded or unreadable.

Cross-check: send backImage plus any cross-check fields (flat or inside crossCheck). The response data.verdict is confirmed, mismatch, or unreadable.

Request​

curl -X POST "https://api.verifik.co/v2/co/cedula/barcode" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VERIFIK_TOKEN" \
  -d '{
    "backImage": "https://example.com/sample-cedula-back.jpg",
    "documentType": "CC"
  }'

Response​

data always includes how many read attempts were used (attempts). Barcode payload fields use Registraduría-style naming where applicable.

FieldWhen presentDescription
verdictAlwaysdecoded or unreadable (decode-only), or confirmed, mismatch, or unreadable (cross-check).
barcodeWhen verdict is not unreadableParsed barcode fields (see below).
decodedDecode-only successSame semantic content as barcode for decode-only responses.
matchScoresCross-checkPer-field similarity scores for fields you supplied.
disagreementsCross-checkFields that did not meet the match threshold.
reasonOptionalHuman-readable detail when verdict is unreadable (for example poor image quality or no barcode detected).
attemptsAlwaysNumber of internal barcode read attempts performed.

barcode object fields (when readable):

FieldDescription
documentNumberNUIP / document number
primerNombreFirst given name
segundoNombreSecond given name (may be empty)
primerApellidoFirst surname
segundoApellidoSecond surname (may be empty)
genderGender
dateOfBirthDate of birth
bloodTypeBlood type
fullNameFull name assembled from barcode parts
{
  "data": {
    "verdict": "decoded",
    "attempts": 1,
    "decoded": {
      "documentNumber": "1234567890",
      "primerNombre": "MARIA",
      "segundoNombre": "ELENA",
      "primerApellido": "LOPEZ",
      "segundoApellido": "GARCIA",
      "gender": "F",
      "dateOfBirth": "15/03/1992",
      "bloodType": "O+",
      "fullName": "MARIA ELENA LOPEZ GARCIA"
    },
    "barcode": {
      "documentNumber": "1234567890",
      "primerNombre": "MARIA",
      "segundoNombre": "ELENA",
      "primerApellido": "LOPEZ",
      "segundoApellido": "GARCIA",
      "gender": "F",
      "dateOfBirth": "15/03/1992",
      "bloodType": "O+",
      "fullName": "MARIA ELENA LOPEZ GARCIA"
    }
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "October 21, 2026 2:30 PM"
  },
  "id": "BC9A2"
}

Fraud Prevention: How It Detects Altered Cédulas​

In Colombian identity fraud, scammers rarely forge a valid 2D barcode from scratch. Instead, bad actors typically doctor the printed text or photo on the front of a stolen or synthetic card using graphic software or physical alterations (e.g. changing the document number or substituting the holder's names).

Two Primary Attack Vectors and How They Fail​

  1. Front-Face Tampering (Altered Names or NUIP)

    • The fraudster modifies the front text, but the rear PDF417 barcode remains unaltered, retaining the legitimate citizen data encoded by the Registraduría Nacional del Estado Civil.
    • When you supply front OCR values via crossCheck (or enable barcode validation in SmartScan / SmartEnroll), Verifik cross-references the front values against the decoded barcode.
    • Any discrepancy yields verdict: "mismatch" and pinpoints the exact tampered fields in disagreements (for example ["documentNumber", "firstName"]). In SmartEnroll and hosted registration flows, this automatically halts automated onboarding and flags the record for manual verification (NEEDS_MANUAL_VERIFICATION).

  2. Barcode Tampering or Synthetic Barcode Insertion

    • If a fraudster attempts to physically alter, smudge, or splice the barcode matrix to conceal their identity or match a forged front, the PDF417 Reed-Solomon error correction codewords fail.
    • The decoding engine fails to reconstruct the symbol, returning verdict: "unreadable" with reason: "barcode_not_detected".
    • If a fraudster attempts to generate an arbitrary custom barcode, Verifik's parser validates the official Registraduría byte structure. Any invalid format is rejected or results in a mismatch when cross-checked against front fields.
Anti-Fraud Best Practice

For automated onboarding and KYC risk assessment, always capture both front and back images of a Colombian Cédula. Any result with verdict: "mismatch" should be treated as an explicit indicator of an altered, counterfeit, or fraudulent document.

Billing​

  • HTTP 200 responses are charged, including when data.verdict is unreadable (the service attempted a billable barcode read).
  • HTTP 409 validation errors (missing backImage, invalid payload, and similar) are not charged, consistent with the Billing and Credit Consumption Policy.
  • Credit amounts depend on your configured feature pricing (client panel, Postman collection, or account manager). This page does not list a fixed price.

Notes​