> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Registrar matriz > Coloca uma organização sob a matriz dela, em um nível e sem unir as duas. ## OpenAPI ````yaml openapi/pt/cell.json POST /v1/identity/parents openapi: 3.1.0 info: title: API de dados da Niadra version: '1' description: >- Escrita, contexto, histórico, objetos, identidade, privacidade e governança de um espaço. Cada espaço tem um endereço estável, com o espaço e a região no nome. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: O espaço, que vem na chave de fonte. region: default: us-east-2 description: A região do espaço, que também vem na chave. security: [] paths: /v1/identity/parents: post: tags: - identity summary: Registrar matriz description: >- Coloca uma organização (a subsidiária) sob a matriz dela. Um nível só: a matriz não tem matriz, a subsidiária não tem subsidiárias e uma organização tem uma matriz por vez. As duas continuam dois perfis, e uma união entre elas é recusada, mesmo forçada, enquanto a matriz estiver em vigor. Os dois lados vêm pelo registro da empresa (`org_registry_hmac`) ou por um id de sistema; domínio de e-mail é pista e nunca serve. O contexto da subsidiária passa a trazer os fatos que a matriz guarda nos próprios ids. **Autenticação.** Token de pessoa do Console com o papel `security`, `integration` (ou admin), ou chave de fonte com o escopo `admin`. operationId: set_parent_v1_identity_parents_post parameters: - in: header name: Idempotency-Key required: true schema: maxLength: 256 minLength: 1 title: Idempotency-Key type: string description: >- Obrigatório. Fica guardado 24 horas com o hash do corpo: repetir com a mesma chave devolve a primeira resposta, e a mesma chave com outro corpo devolve 409 `conflict`. requestBody: content: application/json: schema: $ref: '#/components/schemas/ParentIn' example: organization: type: system_id value: ACC-2201 scope: crm subject_kind: account parent: type: org_registry_hmac value: c2f8e0b4a17d9e36f5a1c0d2b8e4f7a9 subject_kind: account method: system_import required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ParentOut' example: parent_link_id: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e10 org_handle_id: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e05 parent_handle_id: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e11 org_profile_id: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e12 parent_profile_id: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e13 method: system_import valid_from: '2026-09-22T17:10:00Z' valid_to: null description: >- A ligação com a matriz, com o perfil de cada lado. Registrar de novo a mesma matriz devolve a ligação que já existe. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- 422 `invalid_input`: não são duas organizações do mesmo tipo, um lado não vem por registro ou id de sistema, ou é a mesma organização. security: - sourceKey: [] - personToken: [] components: schemas: ParentIn: additionalProperties: false description: >- Uma organização e a matriz dela: um nível só, então a matriz não tem matriz e a subsidiária não tem subsidiárias. As subsidiárias de uma matriz são contas irmãs, cada uma com a própria memória; uma matriz nunca é uma união. Os dois lados vêm pelo registro da empresa (`org_registry_hmac`) ou por um id de sistema. properties: method: default: declared enum: - system_import - declared title: Method type: string organization: $ref: '#/components/schemas/Handle' description: A subsidiária. parent: $ref: '#/components/schemas/Handle' valid_from: anyOf: - format: date-time type: string - type: 'null' title: Valid From valid_to: anyOf: - format: date-time type: string - type: 'null' title: Valid To required: - organization - parent title: ParentIn type: object ParentOut: additionalProperties: false properties: method: enum: - system_import - declared title: Method type: string org_handle_id: description: O identificador da subsidiária. format: uuid title: Org Handle Id type: string org_profile_id: anyOf: - format: uuid type: string - type: 'null' description: O perfil da subsidiária agora. title: Org Profile Id parent_handle_id: format: uuid title: Parent Handle Id type: string parent_link_id: format: uuid title: Parent Link Id type: string parent_profile_id: anyOf: - format: uuid type: string - type: 'null' description: O perfil da matriz agora. title: Parent Profile Id valid_from: format: date-time title: Valid From type: string valid_to: anyOf: - format: date-time type: string - type: 'null' title: Valid To required: - parent_link_id - org_handle_id - parent_handle_id - org_profile_id - parent_profile_id - method - valid_from title: ParentOut type: object Problem: additionalProperties: false description: >- Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de erros versionado. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object Handle: additionalProperties: false description: >- Um identificador de um sujeito num canal ou sistema: um telefone, um e-mail, um id do CRM. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Espaço de nomes dos identificadores com escopo: a conta do WhatsApp Business para `wa_bsuid`, o sistema para `system_id`, o país para `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: >- O padrão é `person`, exceto nos tipos de handle que só identificam organizações. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- O identificador. Normalizado no servidor: E.164 para telefone, minúsculas para e-mail. required: - type - value title: Handle type: object SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- Uma pessoa, uma organização cliente (`account`) ou uma organização que participa sem ser cliente (`partner`). HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- O tipo de identificador. O valor é classificado pelo formato, nunca pelo campo de onde veio. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... personToken: type: http scheme: bearer bearerFormat: JWT ````