Skip to main content

Directory

The following set of endpoints are responsible for Directory management.


Endpoint to create a new link between a key and a transactional account.

Idempotency

The link creation operation is idempotent. This means it is safe to retry in case of temporary failures, such as connection errors or abrupt process termination. The response returned for a repeated request is equivalent to the response given to the first processed request.

To ensure the idempotency of the operation, the request includes an x-request-id header. This field is a UUID version 4 and must be unique in the context of the same participant. The x-request-id is associated with the created link and is used in calculating its CID.

A creation request is considered repeated when the CID of the link contained in the request already exists in DICT.

POST /dict/entries
Requires authorization for the scope: keys.ind.write


Request

{
  "entry": {
    "account": {
      "accountNumber": "0007654321",
      "accountType": "cacc",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00Z",
      "participant": "12345678"
    },
    "key": "+5561988880000",
    "keyType": "phone",
    "owner": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "type": "natural_person"
    }
  },
  "reason": "user_requested",
  "requestId": "a946d533-7f22-42a5-9a9b-e87cd55c0f4d"
}

Responses

The responses below represent Success(201) from the consumption.

// Natural Person Owner
{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "key": "11122233300",
    "keyType": "CPF",
    "account": {
      "participant": "12345678",
      "branch": "0001",
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "openingDate": "2010-01-10T03:00:00.000Z"
    },
    "owner": {
      "type": "NATURAL_PERSON",
      "taxIdNumber": "11122233300",
      "name": "João Silva"
    },
    "creationDate": "2019-11-18T03:00:00.000Z",
    "keyOwnershipDate": "2019-11-18T03:00:00.000Z"
  }
}

Endpoint to obtain a link containing the transactional account details associated with an addressing key.

Request limitation

Key queries are subject to the request rate-limiting policy. The limitation works based on headers sent in the request. Request headers are mandatory for all key types.

The parameter End-User-Document is the identifier of the end user and is used to apply user-scoped rate-limiting policies. It must be filled with the CPF or CNPJ (digits only), depending on the type of the account holder entity.

Statistics

Through the optional parameter IncludeStatistics, it is possible to indicate whether antifraud counter information should be included in the response.

GET /dict/entries/:key
Requires authorization for the scope: keys.ind.read


Request

The request sent to this endpoint does not require a body, only the OAuth authorization headers, parameters, and account certificate.

Responses

The responses below represent Success(200) and failures/errors from the consumption.

// Legal Person
{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "OpenClaimCreationDate": "2023-01-01T10:00:00.000Z",
    "account": {
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00Z",
      "participant": "12345678"
    },
    "creationDate": "2023-01-01T10:00:00.000Z",
    "key": "11122233300",
    "keyOwnershipDate": "2023-01-01T10:00:00.000Z",
    "keyType": "cpf",
    "owner": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "tradeName": "Stark Industries",
      "type": "NATURAL_PERSON"
    }
  },
  "responseTime": 0
}

OU

// Legal person includes statistics
{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "OpenClaimCreationDate": "2023-01-01T10:00:00.000Z",
    "account": {
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00Z",
      "participant": "12345678"
    },
    "creationDate": "2023-01-01T10:00:00.000Z",
    "key": "11122233300",
    "keyOwnershipDate": "2023-01-01T10:00:00.000Z",
    "keyType": "cpf",
    "owner": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "tradeName": "Stark Industries",
      "type": "NATURAL_PERSON"
    }
  },
  "keyStatistics": {
    "entries": {
      "distinctAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "fraudMarkers": {
      "applicationFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "distinctFraudReporters": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "muleAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "otherFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "scammerAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "totalFraudTransactionAmount": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "unknownFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "infractionReports": {
      "openReports": 0,
      "openReportsDistinctReporters": 0,
      "rejectedReports": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "spi": {
      "settlements": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    }
  },
  "ownerStatistics": {
    "entries": {
      "registeredAccounts": 0,
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "fraudMarkers": {
      "applicationFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "distinctFraudReporters": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "muleAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "otherFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "scammerAccounts": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "totalFraudTransactionAmount": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "unknownFrauds": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "infractionReports": {
      "openReports": 0,
      "openReportsDistinctReporters": 0,
      "rejectedReports": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "spi": {
      "settlements": {
        "d90": 0,
        "m12": 0,
        "m60": 0
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    }
  },
  "responseTime": 0
}

Endpoint to update a link.

To be used in scenarios of updating account information, client name, and trade name, while remaining with the same PSP.

Only the account information of the link, client name, and trade name can be updated. Other link updates must be done through deletion/inclusion of the link, portability, or ownership claim, depending on the situation.

Restrictions

The following restrictions must be obeyed when updating a link, according to the key type:

  • EVP keys (random) - Alteration is allowed with the reason BRANCH_TRANSFER.
  • Other keys - Alteration is allowed with the reasons USER_REQUESTED or BRANCH_TRANSFER.

Updates the information of a key (the key remains linked to the same PSP, but the information can be updated).

Reason restrictions:
  • EVP keys (random) - Alteration is allowed, but only with the reason TRANSFERENCIA_AGENCIA.
  • Other keys - Alteration is allowed with the reasons SOLICITACAO_USUARIO or TRANSFERENCIA_AGENCIA.
PUT /dict/entries/:key
Requires authorization for the scope: keys.ind.write


Request

{
  "account": {
    "accountNumber": "0007654321",
    "accountType": "cacc",
    "branch": "0001",
    "openingDate": "2010-01-10t03:00:00Z",
    "participant": "12345678"
  },
  "key": "+5561988887777",
  "owner": {
    "name": "joão silva",
    "taxIdNumber": "11122233300",
    "type": "natural_person"
  },
  "reason": "user_requested"
}

Responses

The responses below represent Success(200) and failures/errors from the consumption.

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "entry": {
    "account": {
      "accountnumber": "0007654321",
      "accounttype": "cacc",
      "branch": "0001",
      "openingdate": "2010-01-10t03:00:00.000z",
      "participant": "12345678"
    },
    "creationdate": "2019-11-18t03:00:00.000z",
    "key": "11122233300",
    "keyownershipdate": "2019-11-18t03:00:00.000z",
    "keytype": "cpf",
    "owner": {
      "name": "joão silva",
      "taxidnumber": "11122233300",
      "type": "natural_person"
    }
  },
  "responseTime": 0
}

Endpoint to remove a key link with an account.

POST /dict/entries/:key/delete
Requires authorization for the scope: keys.ind.remove


Request

{
  "reason": "user_requested"
}

Responses

The responses below represent Success(200) and failures/errors from the consumption.

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "key": "+5561988887777"
}

Last updated on