Testlie
Menu

API mocks

On this page

Registraduría identity lookup (Colombia)

A mock of the civil identity check a Colombian KYC flow runs against the Registraduría Nacional del Estado Civil's identification archive. It lets you:

  • read a cédula or tarjeta de identidad record and the document's state;
  • compare what a customer typed with the record, field by field.

The archive has no public API: authorised operators reach it by agreement, each with its own interface. So this mock defines a neutral REST contract, and your adapter maps it to your operator's API.

Synthetic citizens only: no real person's record is in the mock, and a real cédula number returns invented data. Call logs are kept for 7 days, as for every identity mock. Testlie is not affiliated with the Registraduría.

Connect

Create a Registraduría identity lookup under Identity verification, and send Authorization: Bearer <API key> (REGISTRADURIA_API_KEY).

Errors are { "code", "message" }: UNAUTHORIZED (401), INVALID_DOCUMENT_TYPE, INVALID_DOCUMENT_NUMBER and INVALID_BODY (400), NOT_FOUND (404).

API

Call
GET /v1/identities/{documentType}/{documentNumber} The record: firstName, secondName, firstSurname, secondSurname, fullName, birthDate, expeditionDate, expeditionPlace, gender, state, and deathDate for a deceased holder. 404 when it isn't in the archive.
POST /v1/identities/verify { documentType, documentNumber, firstName?, lastName?, birthDate?, expeditionDate?, reference? }. Returns decision, documentState, fields (each MATCH, PARTIAL, NO_MATCH or NOT_PROVIDED), reference and checkedAt. It confirms what you asked about and doesn't hand back the record.
POST /v1/cedulas/consulta { documentType, documentNumber }. The document's validity, as a certificado de vigencia reads it: status (VIGENTE, CANCELADA, CANCELADA_POR_MUERTE, SUSPENDIDA or NO_ENCONTRADA), detail (the finer reason when a status covers several, such as DOBLE_CEDULACION), and firstName, lastName, fullName, expeditionDate, expeditionPlace and deathDate when there is a record. Always 200.
POST /__testlie/identities Seeds a record: { documentType, documentNumber, firstName, secondName?, firstSurname, secondSurname?, birthDate, expeditionDate, expeditionPlace?, gender?, state?, deathDate? }

documentType is CC (cédula de ciudadanía: 3 to 10 digits, no leading zero) or TI (tarjeta de identidad: 10 or 11 digits). Those are the documents the Registraduría issues; a cédula de extranjería comes from Migración Colombia and is refused.

Decision:

  • MATCH: every field you gave matches;
  • PARTIAL_MATCH: some names share words;
  • NO_MATCH: a field doesn't match, or you gave none;
  • NOT_FOUND: the document isn't in the archive;
  • DOCUMENT_NOT_VALID: the document exists but isn't VIGENTE.

Names are compared in upper case, without accents, punctuation or extra spaces. firstName is compared with the first and second names, and lastName with both surnames. The Outcome scenario "decline" answers NO_MATCH to every verification.

Test numbers

Any well-formed number returns a synthetic citizen, the same one each time for this mock. The last three digits pick the document state:

Ends in State
000 Not in the archive (NO_ENCONTRADO; 404, or NOT_FOUND)
111 CANCELADA_POR_MUERTE, with a deathDate
222 CANCELADA_POR_DOBLE_CEDULACION (CANCELADA in a consulta)
333 CANCELADA_POR_SUPLANTACION (CANCELADA in a consulta)
444 EN_TRAMITE (NO_ENCONTRADA with detail: "EN_TRAMITE" in a consulta)
555 SUSPENDIDA
anything else VIGENTE

Seed a record to match the exact names your test data uses: a seeded number wins over the synthetic one.