Get Users by CNPJ

Endpoint used to retrieve users from the institution associated with a given CNPJ, returning enriched profile data including address, schools, custom form answers, and institution details. Results are scoped to the authenticated institution via JWT. Both masked and unmasked formats are accepted, and the CNPJ is validated against the official Brazilian checksum algorithm.

Note: This endpoint is served by api-admin (Node.js/TypeScript). Use the api-admin base URL for your environment (e.g. https://kong.api.toolzz.com.br).

Request Example

curl --request GET \
  --url 'https://kong.api.toolzz.com.br/users/getUsersByCnpj?cnpj=85709119000190' \
  --header 'Authorization: Bearer <token>'

CNPJ with mask (equivalent):

curl --request GET \
  --url 'https://kong.api.toolzz.com.br/users/getUsersByCnpj?cnpj=85.709.119%2F0001-90' \
  --header 'Authorization: Bearer <token>'

Response Example

{
  "data": [
    {
      "id": 1,
      "uuid": "<string>",
      "name": "<string>",
      "email": "<string>",
      "cpf": "<string>",
      "cnpj": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "rg": null,
      "phone": "<string>",
      "ultima_atividade": "<string>",
      "birthday": "<string>",
      "school": {
        "id": 1,
        "titulo": "<string>"
      },
      "schools": [
        {
          "id": 1,
          "titulo": "<string>"
        }
      ],
      "address": null,
      "custom_form": [],
      "institution": [
        {
          "id": 1,
          "subdomain": "<string>",
          "titulo": "<string>"
        }
      ]
    }
  ]
}

---

Request description

Access Token

Parameter	Type	Description	Required
Authorization	String	Access token (“Bearer” must be before the token). Admin role required.	Yes

URL Parameters (Query)

Parameter	Type	Description	Required
cnpj	string	CNPJ with or without formatting (XX.XXX.XXX/XXXX-XX or 14 digits).	Yes

---

Response description

Key	Type	Description
data	array	List of users associated with the given CNPJ.
data.id	number	Unique identifier of the user.
data.uuid	string	Universal Unique Identifier (UUID) of the user.
data.name	string	Full name of the user.
data.email	string	User email address.
data.cpf	string | null	User’s CPF.
data.cnpj	string | null	CNPJ digits only (no formatting).
data.created_at	string | null	User creation timestamp (ISO 8601).
data.updated_at	string | null	Last update timestamp (ISO 8601).
data.rg	string | null	User’s RG document number.
data.phone	string | null	User phone number.
data.ultima_atividade	string | null	Timestamp of last user activity.
data.birthday	string | null	Date of birth (YYYY-MM-DD).
data.school	object | null	Primary school associated with the user.
data.school.id	number	Unique identifier of the school.
data.school.titulo	string	School name.
data.schools	array	All schools associated with the user.
data.address	object | null	User address details (null if not set).
data.custom_form	array	Responses to institution custom form questions.
data.institution	array	Institutions associated with the user.
data.institution.id	number	Unique identifier of the institution.
data.institution.subdomain	string	Institution subdomain.
data.institution.titulo	string	Institution name.

---

Error responses

HTTP	Situation
400	CNPJ parameter not provided.
400	CNPJ is invalid (wrong check digits, wrong length).
400	No users found with this CNPJ in the institution.
403	Missing, expired, or invalid token, or user lacks admin permission.

{
  "message": "The cnpj query field is required"
}

{
  "message": "The provided CNPJ is invalid. Please inform a valid 14-digit CNPJ."
}

{
  "message": "User not exists"
}

---

Security

To access this endpoint, it is necessary to send a valid access token through the authorization header (Authorization) of the request. Additionally, the API is protected by other security measures to safeguard user data.