| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Intro
This API reads a proof of address and returns the data printed on it, already separated into fields: who it is issued to, the address, the service number, the amount and the date.
It works with bills from CFE, TELMEX, TELCEL, MEGACABLE, SKY and IZZI, sent as a JPG, PNG or PDF file.
Besides the extracted data, the answer includes a set of validations that tell you which of those fields the provider considers reliable and which ones you should review by hand.
Important Points
Mandatory Fields
| field | type | required | length | Description |
|---|---|---|---|---|
| comprobante | Base64 | Yes | N/A | The proof of address file encoded in base64. JPG, PNG, JPEG or PDF. |
No credentials required
This service runs on credentials kiban provides, so you do not need to contract the provider or send a vault field: the API key of your account is enough.
The date is normalized when it can be
The provider prints the date the way the bill shows it, for example 12 SEP 19. When it arrives in that shape, kiban cloud converts it to yyyy-mm-dd. When it arrives in any other shape, the field is delivered exactly as the provider sent it, so read fecha defensively instead of assuming a fixed format.
Read the validations, not only the data
A field can be extracted and still not be trustworthy — a blurry scan, a bill whose layout the provider does not fully recognize. The validaciones object grades the fields it can check: OK means the provider is confident, REVISAR means it wants a human to look at it. A response can carry status: OK and still have a field marked REVISAR.
Test the service (test cases)
We have included a query parameter in Sandbox to enable you to query the test cases that we created for running tests. To get a response, fill the testCaseId parameter with any of the following cases:
| Num | Id | Name | Description |
|---|---|---|---|
| 1 | 6939a1b2c3d4e5f600000a01 | Respuesta exitosa | Indicates one successful response with the extracted data |
| 2 | 6939a1b2c3d4e5f600000a02 | Comprobante invalido | Indicates a 400 response when the file is not a valid proof of address |
Test your own test caseIn case you want to test your own test case created in link, you can send in the testCaseId parameter the identifier of the test case you want to use.
For more information visit our knowledge center to know more about test cases
Successful response
Inside the response object you will get the next fields.
| subfield | Description |
|---|---|
| status | Status returned by the provider. |
| tipo | Kind of document that was recognized, for example CFE. |
| codigoValidacion | Code the provider assigns to the validation performed. |
| claveMensaje | Result code of the reading. |
| fecha | Date of the bill. Delivered as yyyy-mm-dd when it can be interpreted. |
| totalPagar | Total amount to pay printed on the bill. |
| numeroServicio | Service number of the account. |
| nombre | Name the bill is issued to. |
| calle | Street and number of the address. |
| referencia | Address reference printed on the bill. |
| colonia | Neighbourhood, as printed. |
| ciudad | City and state, as printed. |
| rmu | Registro de Medición Único of the service. |
| rmu2 | Second RMU printed on the bill, when it carries one. |
| tarifa | Tariff applied to the service. |
| codigoNumerico | Numeric code of the bill's capture line. |
| validaciones | Per-field grade of the reading: OK or REVISAR for fecha, numeroServicio, totalPagar, rmu and tarifa. |
{
"id": "6939a1b2c3d4e5f600000d21",
"createdAt": "2026-05-11T16:03:22.410Z",
"finishedAt": "2026-05-11T16:03:27.882Z",
"duration": 5472,
"status": "SUCCESS",
"request": {
"comprobante": "JVBERi0xLjQKJeLjz9MKMy..."
},
"response": {
"status": "OK",
"tipo": "CFE",
"codigoValidacion": "ga1644346850.852198",
"claveMensaje": "0",
"fecha": "2019-09-12",
"totalPagar": "51.00",
"numeroServicio": "574751100520",
"nombre": "LUISA GUERRERO",
"calle": "AV BENITO JUAREZ MZ L LT 3 14",
"referencia": "MIGUEL HIDALGO Y FCO VILLA",
"colonia": "DIVISION DEL NORTE . C.P. 55200",
"ciudad": "ECATEPEC DE MORELOS , MEX .",
"rmu": "5520075-11-07XAXX-010101001CFE",
"rmu2": "5520075-11-07KAT-010101001CFE",
"tarifa": "01",
"codigoNumerico": "015747511005201909130000000512",
"validaciones": {
"fecha": "REVISAR",
"numeroServicio": "OK",
"totalPagar": "OK",
"rmu": "OK",
"tarifa": "OK"
}
},
"cost": 0
}Listing the possible not success responses
Required fields
You will get a 400 bad request error when the required field is not provided.
[
{
"message": "comprobante is required",
"field": "(root)"
}
]
Use v2 to get the error detailThe body above is the one returned by
v2. Onv1this validation error arrives as a bare 400 with no body, so you will not know which field was rejected.
Invalid proof of address
The file is not a proof of address can read, or it is not one of the supported issuers. You will get a 400 with the execution, where status is INPUT_ERROR and errorMessage carries the reason.
{
"id": "6939a1b2c3d4e5f600000d22",
"createdAt": "2026-05-11T16:05:44.128Z",
"finishedAt": "2026-05-11T16:05:46.006Z",
"duration": 1878,
"status": "INPUT_ERROR",
"errorMessage": "Comprobante inválido"
}Unauthorized
It means that the provided API is incorrect and that you are not authorized to access it. You will not receive a body, only a 401 HTTP code.