Empréstimos e identidade

Dois produtos cadastrais úteis para análise de crédito e KYC: empréstimos (GET /loans) trazem os contratos de crédito do titular com todos os campos do Open Finance Brasil (CET, juros, garantias, parcelas, pagamentos); identidade (GET /identity) traz um objeto único com os dados cadastrais do titular, com campos estendidos PF/PJ no Open Finance.

Todos os endpoints exigem o header X-API-KEY e respondem em https://api.malvo.io. Ambos filtram por itemId (obrigatório).

Empréstimos (`GET /loans`)

curl "https://api.malvo.io/loans?itemId=5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f" \
  -H "X-API-KEY: $MALVO_API_KEY"

const res = await fetch(
  `https://api.malvo.io/loans?itemId=${itemId}`,
  { headers: { "X-API-KEY": apiKey } },
);
const { results: loans } = await res.json();

Exemplo resumido de um contrato:

Loan (resumido)

{
  "id": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
  "itemId": "5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f",
  "contractNumber": "000000721792794",
  "ipocCode": "92792126019929279212650822221989319252576",
  "productName": "Crédito Pessoal Consignado",
  "type": "CREDITO_PESSOAL_COM_CONSIGNACAO",
  "kind": "LOAN",
  "contractDate": "2022-08-01T00:00:00",
  "contractAmount": 50000,
  "currencyCode": "BRL",
  "dueDate": "2028-01-15T00:00:00",
  "installmentPeriodicity": "MONTHLY",
  "CET": 0.29,
  "amortizationScheduled": "SAC",
  "interestRates": [
    {
      "taxType": "EFETIVA",
      "interestRateType": "SIMPLES",
      "taxPeriodicity": "AA",
      "referentialRateIndexerType": "PRE_FIXADO",
      "preFixedRate": 0.6,
      "postFixedRate": 0.55
    }
  ],
  "installments": {
    "typeNumberOfInstallments": "MES",
    "totalNumberOfInstallments": 60,
    "paidInstallments": 12,
    "dueInstallments": 48,
    "pastDueInstallments": 0
  },
  "payments": {
    "contractOutstandingBalance": 41000,
    "releases": [
      {
        "isOverParcelPayment": false,
        "installmentId": "WGx0aExYcEJMVm93TFRsZA",
        "paidDate": "2026-05-21T00:00:00",
        "currencyCode": "BRL",
        "paidAmount": 1000.04
      }
    ]
  }
}

Campos principais

Campo	Tipo	Descrição
`productName`	string	Nome do produto divulgado ao cliente
`type`	string	Subtipo OFB do produto (ex.: `CREDITO_PESSOAL_COM_CONSIGNACAO`), pass-through do `EnumContractProductSubTypeLoans`
`kind`	enum	`LOAN` \| `FINANCING` \| `INVOICE_FINANCING` \| `UNARRANGED_ACCOUNT_OVERDRAFT`
`contractAmount`	number	Valor contratado
`CET`	number	Custo Efetivo Total anual, incluindo todos os encargos (atenção ao nome em CAIXA ALTA)
`installmentPeriodicity`	enum	`MONTHLY`, `WEEKLY`, `FORTNIGHTLY`, `BIMONTHLY`, `QUARTERLY`, `SEMESTERLY`, `YEARLY`, `OTHERS`, `WITHOUT_REGULAR_PERIODICITY`
`amortizationScheduled`	enum	`SAC` \| `PRICE` \| `SAM` \| `WITHOUT_AMORTIZATION_SYSTEM` \| `OTHERS`

Objetos aninhados (campos OFB)

interestRates — taxas de juros

Array com taxType (NOMINAL/EFFECTIVE — o exemplo mostra o PT "EFETIVA"), interestRateType (SIMPLE/COMPOUND), taxPeriodicity, calculation (ex.: "21/252"), referentialRateIndexerType (ex.: PRE_FIXADO), referentialRateIndexerSubType (ex.: TJLP), preFixedRate e postFixedRate (1 = 100%).

installments — parcelas

typeNumberOfInstallments (DAY/WEEK/MONTH/YEAR/…), totalNumberOfInstallments, paidInstallments, dueInstallments, pastDueInstallments, e balloonPayments ({ dueDate, amount: { value, currencyCode } }).

payments — pagamentos

contractOutstandingBalance (saldo necessário para quitar a dívida) e releases, com cada release trazendo isOverParcelPayment (true = pagamento avulso), installmentId, paidDate, paidAmount e overParcel (fees/charges pagos fora da parcela).

contractedFees, contractedFinanceCharges, warranties

Tarifas contratadas, encargos financeiros e garantias. Valores em PT do Open Finance Brasil (ex.: chargeType: "UNICA", type: "JUROS_REMUNERATORIOS_POR_ATRASO", type: "CESSAO_DIREITOS_CREDITORIOS").

Os valores aninhados (juros, encargos, garantias) chegam com os valores crus em português do Open Finance Brasil. Não converta — armazene e emita exatamente o que a camada de conectividade retorna.

Identidade (`GET /identity`)

Retorna um objeto único IdentityResponse (não é uma lista paginada).

curl "https://api.malvo.io/identity?itemId=207f5bcd-312a-439c-abbe-166b6632c980" \
  -H "X-API-KEY: $MALVO_API_KEY"

const res = await fetch(
  `https://api.malvo.io/identity?itemId=${itemId}`,
  { headers: { "X-API-KEY": apiKey } },
);
const identity = await res.json();

IdentityResponse (resumido)

{
  "id": "42888436-62f5-49d2-8cf9-e312c7939509",
  "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
  "fullName": "Francisco Sousa",
  "document": "076.630.975-48",
  "documentType": "CPF",
  "birthDate": "1991-05-01T00:00:00.000Z",
  "jobTitle": "Comercial",
  "addresses": [
    {
      "fullAddress": "Av. Lúcio Costa 1234, Copacabana, Rio de Janeiro, Brasil",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postalCode": "22620-171",
      "type": "Personal"
    }
  ],
  "phoneNumbers": [{ "type": "Personal", "value": "+55 21 99999-1234" }],
  "emails": [{ "type": "Personal", "value": "[email protected]" }],
  "relations": [
    { "type": "Father", "name": "Antônio Sousa" },
    { "type": "Spouse", "name": "Laura Garcia" }
  ]
}

Campos core (todos os conectores)

Campo	Descrição
`fullName`	Nome do titular
`document` / `documentType`	Documento principal formatado (ex.: `"076.630.975-48"`, `"CPF"`)
`taxNumber`	CNPJ associado a conta PJ
`birthDate`	Data de nascimento
`companyName`	Razão social, em conectores PJ
`addresses` / `phoneNumbers` / `emails` / `relations`	Endereços, telefones, e-mails e parentesco (`Mother`/`Father`/`Spouse`)
`investorProfile`	`Conservative` \| `Moderate` \| `Aggressive`

Os conectores de sandbox retornam apenas os campos core — sem qualifications, financialRelationships ou procuradores.

Campos estendidos do Open Finance

Em produção (Open Finance), além dos campos core, estão disponíveis os campos abaixo — sua presença varia por instituição e entre pessoa física (PF) e pessoa jurídica (PJ):

qualifications e financialRelationships (PF e PJ)

qualifications traz companyCnpj, occupationCode/occupationDescription, informedIncome (renda informada: frequency, amount, date), informedPatrimony e — para PJ — economicActivities (CNAEs, um isMain: true) e informedRevenue (faturamento). financialRelationships traz startDate, productsServicesType, procurators, accounts consentidas e, para PF, portabilitiesReceived/paychecksBankLink.

PF — pessoa física

socialName, sex (FEMALE/MALE/OTHER), maritalStatus (SINGLE/MARRIED/…), nationality (hasBrazilianNationality + outras), otherDocuments (CNH/RG/NIF/RNE/OTHER) e passport.

PJ — pessoa jurídica

incorporationDate, parties (BusinessParty[]: sócios/administradores com documentType, shareholding etc.), businessOtherDocuments e companiesCnpj.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Empréstimos e identidade

Empréstimos (`GET /loans`)

Campos principais

Objetos aninhados (campos OFB)

Identidade (`GET /identity`)

Campos core (todos os conectores)

Campos estendidos do Open Finance

Próximos passos

Investimentos

Reconciliação

​Empréstimos (GET /loans)

​Campos principais

​Objetos aninhados (campos OFB)

​Identidade (GET /identity)

​Campos core (todos os conectores)

​Campos estendidos do Open Finance

​Próximos passos

Investimentos

Reconciliação

Empréstimos (`GET /loans`)

Campos principais

Objetos aninhados (campos OFB)

Identidade (`GET /identity`)

Campos core (todos os conectores)

Campos estendidos do Open Finance

Próximos passos