Find Users and Courses by CNPJ

Endpoint used to retrieve users from the institution associated with a given CNPJ, along with their active course enrollments. Results are scoped to the authenticated institution via JWT. Both masked and unmasked CNPJ formats are accepted.

Request Example

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

CNPJ with mask (equivalent):

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

Response Example

[
  {
    "id": 1,
    "uuid": "<string>",
    "name": "<string>",
    "username": null,
    "email": "<string>",
    "cnpj": "<string>",
    "courses": [
      {
        "course_id": 1,
        "current_score": null,
        "course_concluded": 0,
        "conclusion_date": null,
        "class_ids": "<string>",
        "school_ids": "<string>",
        "enrollment_id": 1,
        "expiration_date": null,
        "created_at": "<string>",
        "updated_at": "<string>"
      }
    ]
  }
]

The cnpj field is always returned without formatting (digits only). When the user exists but has no courses, the courses field returns a message object instead of an array: {"message": "Não existem cursos matriculados para o CNPJ informado."}.

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
`id`	number	Unique identifier of the user.
`uuid`	string	Universal Unique Identifier (UUID) of the user.
`name`	string	Full name of the user.
`username`	string \| null	Username (may be null).
`email`	string	User email address.
`cnpj`	string	CNPJ digits only (no formatting).
`courses`	array	List of active course enrollments for this user.
`courses.course_id`	number	Unique identifier of the course.
`courses.current_score`	number \| null	Current score in the course.
`courses.course_concluded`	number	Completion status: `1` = completed, `0` = in progress.
`courses.conclusion_date`	string \| null	Conclusion date (`null` if not concluded).
`courses.class_ids`	string	Comma-separated class IDs the user belongs to.
`courses.school_ids`	string	Comma-separated school IDs linked to the enrollment.
`courses.enrollment_id`	number	Unique identifier of the enrollment record.
`courses.expiration_date`	string \| null	Enrollment expiration date (`null` if no expiry).
`courses.created_at`	string	Enrollment creation timestamp (ISO 8601).
`courses.updated_at`	string	Last update timestamp (ISO 8601).

Error responses

HTTP	Situation
`404`	No users found with this CNPJ in the institution.
`422`	CNPJ is invalid (wrong check digits, wrong length).
`422`	`cnpj` parameter not provided.
`403`	User lacks admin permission.
`429`	Rate limit exceeded (100 req/min).

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

{
  "cnpj": ["The cnpj field is required."]
}

{
  "message": "Nenhum usuário encontrado para o CNPJ informado."
}

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.