Classifier

Document classification services.

The service finds the documents inside the file you send, and our AI models classify them.

The classifier only answers which document that is — it does not read anything written inside the document. To also receive the fields written on it, use Full OCR.

Request

POST /classify/v3

Parameters

This endpoint has no query parameters. Unlike other endpoints, an unknown query parameter does not return 422 here: it is simply ignored.

Headers

Authorization: ApiKey <your-api-key>

This endpoint also accepts the JWT token, in the format Authorization: Bearer <accessToken>. See JWT Token.

Accepted files

As a parameter, this endpoint expects the file or image to be classified. For more information, see here.

Item	Value
Formats	image/png, image/jpeg, application/pdf
Files per call	1 file
Maximum size (multipart)	15 MB

TIP

This endpoint accepts only one file or image at a time.

The form field name is up to you — it comes back in the response, in metadata.filesInfo. If more than one file is sent, the request is rejected with 422.

In a multi-page PDF, each page is analyzed separately, and every document recognized becomes an entry in data.

Besides multipart/form-data, the file can be sent as JSON, in the base64 field, as described in Sending files.

Example request

curl -i -X POST 'https://api-homolog.nxcd.app/classify/v3' \
  --header 'Authorization: ApiKey YOUR_API_KEY' \
  --form 'documento=@./cnh.jpg'

Response

The fields below describe v3. The other versions return a data in a different format — see Versions.

Field	Description	Type	Notes
id	Unique ID of the request	String
version	API version	String
data	List of the analysis results	Object[]	Comes back empty when nothing was recognized
data.classification	Object with the classification details	Object
data.classification.type	Type of the document found	String	See the list of accepted documents
data.classification.subtype	Subtype of the document found	String	See the list of accepted documents
data.classification.country	Country of origin of the document found	String	See the list of accepted documents
data.classification.sides	List with the side of the document found	Object[]	Always contains a single item
data.classification.sides.side	Side of the document that was found	String	Enum: (OnlyFront, OnlyBack, FrontAndBack)
data.classification.sides.page	Page where the document was found	Number	Starts at 0
data.classification.sides.fieldname	Name of the field the file was sent in	String
data.classification.sides.confidence	Confidence of the classification	Number	Value already filtered internally
metadata	Metadata about the request (to support debugging)	Object
metadata.filesInfo	List with the metadata of the files	Object[]
metadata.filesInfo.fieldname	Name of the parameter the file was sent in	String
metadata.filesInfo.name	Name of the file that was sent	String
metadata.filesInfo.size	Size of the file that was sent, in bytes	Number
metadata.filesInfo.pages	Number of pages in the file	Number	1 for images
metadata.filesInfo.mimetype	MIME type of the file that was sent	String
metadata.filesInfo.encoding	Encoding of the file that was sent	String
metadata.filesInfo.sha256	SHA256 of the file that was sent	String
metadata.timeSpent	Processing time of the request	Number	In milliseconds

TIP

confidence - We already filter internally so that only documents above the expected confidence are returned. We recommend filtering on this field only in specific cases, where the default filter does not meet your needs or where you want to raise the bar on the minimum quality you accept.

TIP

The response is always a list (the data field), because a file/image may contain no identity document, one, or several. To make this data simpler to consume, the list is sorted from the best to the worst result: if you expect a single document, take the first item of the list. If the list is empty, no document could be identified in that image.

JSON examples

Here are some examples of the response in JSON.

1. Example when an identity document is found in the image

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v3",
  "data": [
    {
      "classification": {
        "type": "DriversLicense",
        "subtype": "Printed",
        "country": "BRA",
        "sides": [
          {
            "side": "FrontAndBack",
            "page": 0,
            "fieldname": "documento",
            "confidence": 0.99
          }
        ]
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      }
    ],
    "timeSpent": 10000
  }
}

2. Example when no document is found in the image

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v3",
  "data": [],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      }
    ],
    "timeSpent": 10000
  }
}

Response headers

Header	When it appears
Nextid-ReqId	On every response. Carries the request identifier, the same one as the id field in the body.

Errors

Code	When it happens
401 Unauthorized	API key or JWT token missing, invalid, or without the nextid.classifications.classify permission.
404 Not Found	The version stated in the URL does not exist. Only v2, v3, v4 and v5 are accepted.
406 Not Acceptable	The body was sent as JSON, but without the base64 field.
413 Payload Too Large	The file sent as multipart/form-data is larger than 15 MB.
415 Unsupported Media Type	The Content-Type header is missing or is not supported.
422 Unprocessable Entity	The file format is not accepted, or more than one file was sent in the same call.
500 Internal Server Error	Unexpected failure during processing.

A document the classifier does not recognize is not an error: the response comes back 200 with an empty data.

The error response format is described in HTTP response codes.

Versions

The version documented on this page is v3, called at /classify/v3. It is the one that uses the same type vocabulary as the list of accepted identity documents below.

‼️ Omitting the version sends the call to v2

POST /classify, with no version in the path, is served by v2, which responds in a different format. Always state the version in the URL.

Version	Status	What changes
v3	Recommended	classification with type, subtype, country and sides as a list.
v4	Available	sides disappears from classification: what is left is a consolidated side (Front, Back, FrontAndBack) and a sameImage. page, fieldname and confidence move to metadata.filesInfo[].details.
v5	Available	Accepted in the URL. Returns the same response body as v4, with version: "v5".
v2	Legacy	Carries neither subtype nor country. type uses the old vocabulary (CNH, RG, CPF, OTHERS…) and the side comes in face. This is the version that answers when no version is stated in the URL.

What changes in v2

Each item of data carries page and fieldname at the root, and classification is reduced to three fields:

Field	Description	Type
data.page	Page where the document was found	Number
data.fieldname	Name of the field the file was sent in	String
data.classification.type	CNH, RG, CPF, PROOF-OF-RESIDENCE, SELFIE, IMPRESSOS, CARTAOCREDITO or OTHERS	String
data.classification.face	front, back or front-back	String
data.classification.confidence	Confidence of the classification	Number

Every type outside that list — passport, professional council card, foreign document — is returned as OTHERS in v2.

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v2",
  "data": [
    {
      "page": 0,
      "fieldname": "documento",
      "classification": {
        "confidence": 0.99,
        "type": "CNH",
        "face": "front-back"
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      }
    ],
    "timeSpent": 10000
  }
}

What changes in v4 and v5

classification no longer has the sides list and now carries an already consolidated side, in the Front / Back / FrontAndBack vocabulary. page, fieldname and confidence leave classification and reappear in metadata.filesInfo[].details.

Field	Description	Type
data.classification.type	Type of the document found	String
data.classification.subtype	Subtype of the document found	String
data.classification.country	Country of origin of the document found	String
data.classification.side	Consolidated side: Front, Back or FrontAndBack	String
data.classification.sameImage	true when front and back came from the same page of the same file	Boolean
metadata.filesInfo[].details	One entry per side recognized in that file	Object[]
metadata.filesInfo[].details[].side	Side recognized: Front, Back or FrontAndBack	String
metadata.filesInfo[].details[].page	Page where it was recognized. Starts at 0.	Number
metadata.filesInfo[].details[].confidence	Confidence of the classification of that side	Number

🚧 In v4 and v5 the list does not come sorted by confidence

confidence leaves classification before the sorting step, so sorting by confidence does not happen in these versions: when more than one document is recognized in the same file, data comes in the order the documents were processed, not from the best to the worst. If you depend on that order, use v3.

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v4",
  "data": [
    {
      "classification": {
        "country": "BRA",
        "type": "DriversLicense",
        "subtype": "Printed",
        "side": "FrontAndBack",
        "sameImage": true
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0",
        "details": [
          {
            "side": "FrontAndBack",
            "confidence": 0.99,
            "page": 0
          }
        ]
      }
    ],
    "timeSpent": 10000
  }
}

Identity types and subtypes

List of the types, subtypes and sides of every identity document recognized by our classifier. Note that the list below follows this order: country of origin, type, subtype and side.

E.g.:

• Country
  • Type
    • Subtype
      • Side

---

Full list

ARG

DriversLicense

• empty
  • OnlyFront

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

BHR

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

BRA

FederalCouncil

• Accounting_Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Accounting_Plastic
  • OnlyBack
  • OnlyFront
• Administration_v1
  • OnlyBack
  • OnlyFront
• Administration_v2
  • OnlyBack
  • OnlyFront
• ArchitectureAndUrbanism
  • OnlyFront
• Biology
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Biomedicine
  • OnlyBack
  • OnlyFront
• Chemistry
  • OnlyBack
  • OnlyFront
• Dentistry
  • OnlyBack
  • OnlyFront
• EngineeringAndAgronomy_Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• EngineeringAndAgronomy_Plastic
  • OnlyBack
  • OnlyFront
• Fishery
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Lawyers
  • OnlyBack
  • OnlyFront
• Medicine_Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Medicine_Plastic
  • OnlyBack
  • OnlyFront
• Musician
  • OnlyBack
  • OnlyFront
• Nursing_v1
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Nursing_v2
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Nutrition
  • OnlyBack
  • OnlyFront
• Pharmacy_Paper
  • OnlyBack
  • OnlyFront
• Pharmacy_Plastic
  • OnlyBack
  • OnlyFront
• PhysicalEducation
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Psychology
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Radiology
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• SalesRepresentatives
  • OnlyFront
• SocialService
  • OnlyBack
  • OnlyFront
• Veterinary
  • OnlyBack
  • OnlyFront

DriversLicense

• BoatAndVessel
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Printed
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Resolution2021Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Resolution2021Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack

FederalID

• Decree2018Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Decree2018Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Decree2018Plastic
  • OnlyBack
  • OnlyFront
• Decree2022Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• MainModel
  • OnlyBack
  • OnlyFront
  • FrontAndBack

FederalRevenueService

• CIC
  • OnlyFront
• Plastic
  • OnlyFront
• Printed
  • OnlyFront
• Temporary
  • OnlyFront

FirefighterID

• RioDeJaneiro
  • OnlyBack
  • OnlyFront

ForeignID

• empty
  • OnlyBack
  • OnlyFront

MigratoryRegister

• empty
  • OnlyBack
  • OnlyFront

RefugeRequest

• empty
  • OnlyBack
  • OnlyFront
  • FrontAndBack

MilitaryID

• Airforce
  • OnlyBack
  • OnlyFront
• Army_Paper
  • OnlyBack
  • OnlyFront
• Army_Temporary
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• MilitaryDischarge
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Navy_Paper
  • OnlyBack
  • FrontAndBack
• Navy_Plastic
  • OnlyBack
  • OnlyFront

Passport

• empty
  • OnlyFront

PoliceID

• Alagoas
  • OnlyFront
• Amazonas
  • OnlyFront
• Bahia
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Ceara
  • OnlyFront
• DistritoFederal
  • OnlyBack
  • OnlyFront
• EspiritoSanto
  • OnlyFront
• MatoGrosso
  • OnlyBack
  • OnlyFront
• MatoGrossoDoSul
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• MinasGerais_Paper
  • OnlyBack
  • OnlyFront
• MinasGerais_Plastic
  • OnlyFront
• Para
  • OnlyBack
  • OnlyFront
• Paraiba
  • OnlyBack
  • OnlyFront
• Pernambuco
  • OnlyBack
  • OnlyFront
• Piaui
  • OnlyFront
• RioDeJaneiro
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• RioGrandeDoNorte
  • OnlyFront
• SaoPaulo
  • OnlyBack
  • OnlyFront
  • FrontAndBack

ProofOfResidence

• Celesc
  • OnlyFront
• Cemig
  • OnlyFront
• Claro
  • OnlyFront
• CoelbaCelpe
  • OnlyFront
• Copel
  • OnlyFront
• Cpfl
  • OnlyFront
• Edp
  • OnlyFront
• Enel
  • OnlyFront
• Energisa
  • OnlyFront
• Equatorial
  • OnlyFront
• Light
  • OnlyFront
• Rge
  • OnlyFront
• Sabesp
  • OnlyFront
• Saneago
  • OnlyFront
• Tim
  • OnlyFront
• Vivo
  • OnlyFront

Transportation

• ANTT
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• CRLV_Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• CRLV_Printed
  • OnlyBack
  • OnlyFront
  • FrontAndBack

VoterID

• empty
  • OnlyBack
  • OnlyFront

WorkAndSocialSecurityRegistry

• Handwritten
  • OnlyBack
  • OnlyFront
• Printed
  • OnlyBack
  • OnlyFront

---

COL

DriversLicense

• empty
  • OnlyFront

FederalID

• empty
  • OnlyBack
  • OnlyFront

Passport

• empty
  • OnlyFront

---

ESP

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

ITA

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

MAR

DriversLicense

• empty
  • OnlyBack
  • OnlyFront

---

MEX

VoterID

• empty
  • OnlyFront

---

PAK

FederalID

• empty
  • OnlyFront
  • OnlyBack

---

PER

FederalID_Paper

• empty
  • OnlyFront

FederalID_Plastic

• empty
  • OnlyFront

Passport

• empty
  • OnlyFront

---

PRT

FederalID

• empty
  • OnlyFront
  • OnlyBack

Passport

• empty
  • OnlyFront

---

PRY

FederalID

• empty
  • OnlyFront

---

URY

FederalID

• empty
  • OnlyFront

---

USA

DriversLicense

• Florida
  • OnlyFront
• Georgia
  • OnlyFront

Passport

• empty
  • OnlyFront

SocialSecurityID

• empty
  • OnlyFront

---

VEN

FederalID

• empty
  • OnlyFront

Passport

• empty
  • OnlyFront