O tomador é a pessoa física que irá contratar a operação de crédito. O id retornado no cadastro é utilizado como borrower_id na criação da proposta de crédito.

Cadastrar de um Tomador

POST /banking/originator/persons

Headers

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <token>`
`Content-Type`	Sim	`application/json`

Campos do body

Campos obrigatórios

Campo	Tipo	Descrição
`full_name`	string	Nome completo do tomador
`taxpayer_id`	string	CPF ou CNPJ sem pontuação (`.` `-` `/`)
`nationality`	string	Nacionalidade. Ex.: `"Brasileiro"`
`email_address`	string	E-mail do tomador
`occupation`	string	Profissão do tomador
`birth_date`	string	Data de nascimento no formato `YYYY-MM-DD`
`phone`	object	Telefone do tomador (ver abaixo)

Objeto phone

Campo	Tipo	Descrição
`country_code`	string	DDI. Ex.: `"+55"` para Brasil
`area_code`	string	DDD. Ex.: `"11"` para São Paulo
`number`	string	Número do telefone sem formatação

Dados bancários para desembolso (obrigatório ao menos um)

Opção 1 — Chave Pix

Campo	Tipo	Descrição
`pix.key`	string	Chave Pix
`pix.key_type`	string	Tipo da chave: `TAXPAYER_ID`, `EMAIL`, `PHONE_NUMBER`, `ALEATORY_KEY`

Sandbox: utilize a chave mágica 4ca519ef-0ccc-4c41-b58b-c88f1f47d8ab com key_type: ALEATORY_KEY para simular desembolsos em ambiente de testes.

Opção 2 — Conta bancária

Campo	Tipo	Descrição
`external_bank_account.bank_code`	string	Código do banco
`external_bank_account.bank_account`	string	Número da conta
`external_bank_account.bank_account_digit`	string	Dígito verificador da conta
`external_bank_account.bank_branch`	string	Agência
`external_bank_account.bank_account_type`	string	Tipo de conta. Ex.: `"CACC"` (conta corrente)
`external_bank_account.ispb_code`	string	Código ISPB da instituição
`external_bank_account.tax_payer_id`	string	CPF ou CNPJ do titular da conta
`external_bank_account.name`	string	Nome do titular da conta

Campos opcionais relevantes

Campo	Tipo	Descrição
`sex`	string	Sexo: `MALE` \| `FEMALE`
`marital_status`	string	Estado civil: `SINGLE`, `MARRIED`, `DIVORCED`, `WIDOWED`
`marital_property_system`	string	Regime de bens: `NO_COMMUNION`, `PARTIAL_COMMUNION`, `UNIVERSAL_COMMUNION`, `SEPARATION_OF_ASSETS`
`pep`	boolean	Pessoa Exposta Politicamente
`mothers_name`	string	Nome da mãe
`monthly_income`	number	Renda mensal
`id_document`	object	Documento de identidade (ver abaixo)
`address`	object	Endereço do tomador (ver abaixo)
`external_id`	string	Identificador externo do originador
`custom_variables`	object	Variáveis customizadas do originador

Objeto id_document

Campo	Tipo	Descrição
`number`	string	Número do documento
`issuer`	string	Órgão emissor. Ex.: `"SSP/SP"`
`issue_date`	string	Data de emissão no formato `YYYY-MM-DD`
`type`	string	Tipo: `NATIONAL_ID`, `PROOF_OF_INCOME`, `SCR_AUTHORIZATION,'OTHER`

Objeto address

Campo	Tipo	Descrição
`street_name`	string	Logradouro
`street_number`	integer	Número
`postal_code`	string	CEP sem hífen
`district`	string	Bairro
`city`	string	Cidade
`state_code`	string	UF. Ex.: `"SP"`
`country_code`	string	Código do país. Ex.: `"BRA"`
`extra_info`	string	Complemento

Exemplo — mínimo necessário

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/persons' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "full_name": "Felipe Tavares",
    "taxpayer_id": "64721458908",
    "nationality": "Brasileiro",
    "email_address": "felipe@email.com",
    "occupation": "Analista de Onboarding",
    "birth_date": "2001-01-01",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999999999"
    }
  }'

Exemplo — com chave Pix para desembolso

Sandbox: utilize a chave 4ca519ef-0ccc-4c41-b58b-c88f1f47d8ab para simular desembolsos em ambiente de testes.

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/persons' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "full_name": "Felipe Tavares",
    "taxpayer_id": "64721458908",
    "nationality": "Brasileiro",
    "email_address": "felipe@email.com",
    "occupation": "Analista de Onboarding",
    "birth_date": "2001-01-01",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999999999"
    },
    "pix": {
      "key": "4ca519ef-0ccc-4c41-b58b-c88f1f47d8ab",
      "key_type": "ALEATORY_KEY"
    }
  }'

Exemplo — com conta bancária para desembolso

curl --request POST \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/persons' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "full_name": "Felipe Tavares",
    "taxpayer_id": "64721458908",
    "nationality": "Brasileiro",
    "email_address": "felipe@email.com",
    "occupation": "Analista de Onboarding",
    "birth_date": "2001-01-01",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999999999"
    },
    "external_bank_account": {
      "bank_code": "000",
      "bank_account": "00000",
      "bank_account_digit": "0",
      "bank_branch": "00000"
    }
  }'

Resposta (HTTP 201)

{
  "id": "9075aef9-0ad7-4f62-8ec9-10da2336ab0e",
  "full_name": "Felipe Tavares",
  "taxpayer_id": "64721458908",
  "nationality": "Brasileiro",
  "email_address": "felipe@email.com",
  "occupation": "Analista de Onboarding",
  "birth_date": "2001-01-01",
  "phone": {
    "country_code": "+55",
    "area_code": "11",
    "number": "999999999",
    "formatted_number": "+55119999999999"
  },
  "pix": {
    "key": "4ca519ef-0ccc-4c41-b58b-c88f1f47d8ab",
    "key_type": "ALEATORY_KEY"
  },
  "external_bank_account": null,
  "status": "APPROVED",
  "created_at": "2026-04-17T19:32:28.766544Z",
  "updated_at": "2026-04-17T19:32:28.766544Z",
  "version": 1
}

O campo id retornado deve ser utilizado como borrower_id na criação da proposta de crédito.

Consultar tomador

GET /banking/originator/persons/{person_id}

Exemplo

curl --request GET \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/persons/9075aef9-0ad7-4f62-8ec9-10da2336ab0e' \
  --header 'Authorization: Bearer <seu_token>'

Resposta (HTTP 200)

Retorna o objeto completo do tomador no mesmo formato da resposta do cadastro.

Atualizar tomador

PUT /banking/originator/persons/{person_id}

Atualiza os dados de um tomador existente. O body aceita os mesmos campos do cadastro. Apenas os campos enviados serão atualizados.

Path parameter

Parâmetro	Tipo	Descrição
`person_id`	UUID	Identificador do tomador a ser atualizado

Exemplo — atualizar chave Pix

curl --request PUT \
  'https://sandbox.platform.flowfinance.com.br/banking/originator/persons/9075aef9-0ad7-4f62-8ec9-10da2336ab0e' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "pix": {
      "key": "felipe@email.com",
      "key_type": "EMAIL"
    }
  }'