Institutions

Institutions, privacy policy and terms of use of each one.

List the institutions the person can see

GET /instituicoes

Access: Requires the capability LER, in some scope (the response only includes what the person can see). Success status: 200.

Query parameters

Parameter	Type	Required	Constraints	Description
`busca`	`string`	no	to 100 characters	Search text (name or email, depending on the route).
`limite`	`integer`	no	1…200; default: `50`	How many items per page (1 to 200; the default varies by route, usually 50).
`deslocamento`	`integer`	no	0…100000; default: `0`	How many items to skip, for paging (up to 100000).
`inativos`	`"true"` \| `"false"`	no	default: `"false"`	`true` also includes inactive records.

Response

list of InstituicaoDto (+ total)

Field	Type	Required	Description
`id`	`string (uuid)`	yes
`sigla`	`string`	yes
`nome`	`string`	yes
`ativo`	`boolean`	yes
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` or `null`	yes
`timezone`	`string`	yes
`retencaoMeses`	`integer` or `null`	yes
`controladorNome`	`string` or `null`	no	The institution's privacy data; the API always sends them (null when not provided).
`encarregadoNome`	`string` or `null`	no
`contatoPrivacidade`	`string` or `null`	no

On error: ErroApi model.

Example

bash

curl -X GET "$API/instituicoes" -H "Authorization: Bearer $TOKEN"

Create an institution and invite its first curator

POST /instituicoes

Access: Requires the capability PLATAFORMA. Success status: 201.

Request body (InstituicaoCriar)

Field	Type	Required	Constraints	Description
`sigla`	`string`	yes	`^[A-Za-z0-9][A-Za-z0-9._-]{1,19}$`
`nome`	`string`	yes	1–200 characters
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` or `null`	no
`timezone`	Fuso	no
`retencaoMeses`	`integer` or `null`	no	1…600
`curador`	`object`	no		The institution's first curator: receives the invitation by email.
`curador.email`	Email	yes
`curador.nome`	`string`	yes	1–200 characters

Response

InstituicaoDto

Field	Type	Required	Description
`id`	`string (uuid)`	yes
`sigla`	`string`	yes
`nome`	`string`	yes
`ativo`	`boolean`	yes
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` or `null`	yes
`timezone`	`string`	yes
`retencaoMeses`	`integer` or `null`	yes
`controladorNome`	`string` or `null`	no	The institution's privacy data; the API always sends them (null when not provided).
`encarregadoNome`	`string` or `null`	no
`contatoPrivacidade`	`string` or `null`	no

On error: ErroApi model.

Example

bash

curl -X POST "$API/instituicoes" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"sigla":"texto","nome":"texto"}'

Read an institution

GET /instituicoes/{instituicaoId}

Access: Requires the capability LER over institution (params.instituicaoId). Success status: 200.

Path parameters

Parameter	Type	Required	Constraints	Description
`instituicaoId`	`string (uuid)`	yes		Institution id.

Response

InstituicaoDto

Field	Type	Required	Description
`id`	`string (uuid)`	yes
`sigla`	`string`	yes
`nome`	`string`	yes
`ativo`	`boolean`	yes
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` or `null`	yes
`timezone`	`string`	yes
`retencaoMeses`	`integer` or `null`	yes
`controladorNome`	`string` or `null`	no	The institution's privacy data; the API always sends them (null when not provided).
`encarregadoNome`	`string` or `null`	no
`contatoPrivacidade`	`string` or `null`	no

On error: ErroApi model.

Example

bash

curl -X GET "$API/instituicoes/{instituicaoId}" -H "Authorization: Bearer $TOKEN"

Update an institution

PATCH /instituicoes/{instituicaoId}

Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.

Path parameters

Parameter	Type	Required	Constraints	Description
`instituicaoId`	`string (uuid)`	yes		Institution id.

Request body (InstituicaoAtualizar)

Field	Type	Required	Constraints	Description
`nome`	`string`	no	1–200 characters
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` or `null`	no
`timezone`	Fuso	no
`retencaoMeses`	`integer` or `null`	no	1…600
`controladorNome`	`string` or `null`	no	1–200 characters	Privacy (LGPD): `null` clears the value and goes back to the platform default.
`encarregadoNome`	`string` or `null`	no	1–200 characters
`contatoPrivacidade`	Email or `null`	no
`ativo`	`boolean`	no

Response

InstituicaoDto

Field	Type	Required	Description
`id`	`string (uuid)`	yes
`sigla`	`string`	yes
`nome`	`string`	yes
`ativo`	`boolean`	yes
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` or `null`	yes
`timezone`	`string`	yes
`retencaoMeses`	`integer` or `null`	yes
`controladorNome`	`string` or `null`	no	The institution's privacy data; the API always sends them (null when not provided).
`encarregadoNome`	`string` or `null`	no
`contatoPrivacidade`	`string` or `null`	no

On error: ErroApi model.

Example

bash

curl -X PATCH "$API/instituicoes/{instituicaoId}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'

Read the institution's current privacy policy

GET /instituicoes/{instituicaoId}/politica-privacidade

Access: Requires the capability LER over institution (params.instituicaoId). Success status: 200.

Path parameters

Parameter	Type	Required	Constraints	Description
`instituicaoId`	`string (uuid)`	yes		Institution id.

Response

PoliticaDto

Field	Type	Required
`versao`	`integer` or `null`	yes
`textos`	TermoTextos	yes
`publicadoEm`	`string (date-time)` or `null`	yes
`urlPublica`	`string`	yes

On error: ErroApi model.

Example

bash

curl -X GET "$API/instituicoes/{instituicaoId}/politica-privacidade" -H "Authorization: Bearer $TOKEN"

Publish a new version of the privacy policy

PUT /instituicoes/{instituicaoId}/politica-privacidade

Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.

Path parameters

Parameter	Type	Required	Constraints	Description
`instituicaoId`	`string (uuid)`	yes		Institution id.

Request body (TermoPublicar)

Field	Type	Required	Constraints	Description
`textos`	TermoTextos	yes

Response

PoliticaDto

Field	Type	Required
`versao`	`integer` or `null`	yes
`textos`	TermoTextos	yes
`publicadoEm`	`string (date-time)` or `null`	yes
`urlPublica`	`string`	yes

On error: ErroApi model.

Example

bash

curl -X PUT "$API/instituicoes/{instituicaoId}/politica-privacidade" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"textos":{}}'

Read the institution's current terms of use

GET /instituicoes/{instituicaoId}/termo

Access: Requires the capability LER over institution (params.instituicaoId). Success status: 200.

Path parameters

Parameter	Type	Required	Constraints	Description
`instituicaoId`	`string (uuid)`	yes		Institution id.

Response

TermoDto

Field	Type	Required
`versao`	`integer` or `null`	yes
`textos`	TermoTextos	yes
`publicadoEm`	`string (date-time)` or `null`	yes

On error: ErroApi model.

Example

bash

curl -X GET "$API/instituicoes/{instituicaoId}/termo" -H "Authorization: Bearer $TOKEN"

Publish a new version of the terms of use

PUT /instituicoes/{instituicaoId}/termo

Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Success status: 200.

Path parameters

Parameter	Type	Required	Constraints	Description
`instituicaoId`	`string (uuid)`	yes		Institution id.

Request body (TermoPublicar)

Field	Type	Required	Constraints	Description
`textos`	TermoTextos	yes

Response

TermoDto

Field	Type	Required
`versao`	`integer` or `null`	yes
`textos`	TermoTextos	yes
`publicadoEm`	`string (date-time)` or `null`	yes

On error: ErroApi model.

Example

bash

curl -X PUT "$API/instituicoes/{instituicaoId}/termo" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"textos":{}}'

Institutions ​

List the institutions the person can see ​

Create an institution and invite its first curator ​

Read an institution ​

Update an institution ​

Read the institution's current privacy policy ​

Publish a new version of the privacy policy ​

Read the institution's current terms of use ​

Publish a new version of the terms of use ​

Institutions

List the institutions the person can see

Create an institution and invite its first curator

Read an institution

Update an institution

Read the institution's current privacy policy

Publish a new version of the privacy policy

Read the institution's current terms of use

Publish a new version of the terms of use