> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# XP as a data source
> Bring data from the XP Data Access partner API to Nekt.
XP Data Access is XP Inc.'s partner API. It gives brokerage offices fine-grained, non-consolidated access to their business data, including positions and custody, movements, inflows, products, accounts, advisors, and commissions.
XP Data Access is a restricted partner API. Access is granted by XP only to offices that have completed XP's onboarding and Security Assessment. Nekt cannot provision test access on your behalf, so you configure this source with the credentials and certificate that XP issued to your office.
## Prerequisites
Before configuring the source, your office needs the following from XP. They are all obtained through the XP developer portal and Security Assessment:
* **Client ID and Client Secret** — OAuth2 credentials generated in the developer portal (Gestão → Credenciais). The client secret is shown only once.
* **Subscription Key** — sent by XP by email after the Security Assessment is approved (the `Ocp-Apim-Subscription-Key` value).
* **Digital certificate** — a client-authentication certificate (mTLS) issued with your office's data. It must have the Client Authentication extended key usage (`1.3.6.1.5.5.7.3.2`) and OCSP enabled, and it must not include the TLS Web Server Authentication usage. ICP-Brasil certificates are accepted.
* **IP allow-listing** — XP releases access by IP range. The IPs that reach the API are registered in the Security Assessment ticket.
Every request to XP requires the OAuth token, the client certificate, and the subscription key together. A missing or invalid certificate, key, or token results in an authentication error.
## Configuring XP as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the XP option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
Provide the credentials and certificate that XP issued to your office:
* **Environment**: The XP Data Access environment to connect to. Choose `homologation` to validate the integration first, or `production` for live data. Each environment has its own credentials, certificate, and scope.
* **Client ID**: The OAuth2 client ID from the developer portal.
* **Client Secret**: The OAuth2 client secret from the developer portal.
* **Subscription Key**: The `Ocp-Apim-Subscription-Key` value sent by XP.
* **Certificate file (.pfx)**: The digital certificate file in PKCS#12 format (`.pfx`/`.p12`), uploaded exactly as delivered by the certificate authority — no conversion needed.
* **Certificate Password**: The password of the `.pfx` certificate file. Leave empty only if the certificate has no password.
* **Partner Name**: An identifier for your office, used in the request `User-Agent`.
* **Start Date** (advanced): The earliest record date to sync for incremental streams.
If you prefer to provide the certificate as PEM text instead of uploading the `.pfx` file, use the advanced settings: **Client Certificate (PEM)** and **Private Key (PEM)** accept the certificate and key in PEM format (leave the private key empty if the certificate already includes it). The uploaded `.pfx` file takes precedence when both are provided.
Once you're done, click **Next**.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/get-started/core-concepts/triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
XP Data Access publishes data with a one-day delay (D-1) and updates only on business days, following the B3 banking calendar. A daily trigger is usually enough.
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from XP and their corresponding fields. Most streams sync incrementally: dimensions by `lastUpdate`, fact tables by `dimTimeCode` (a `YYYYMMDD` time key), and Positivador by `positionDate`.
Account dimension. Tracks account versions over time (SCD Type 2) with validity windows; `currentRegisterIndicator` marks the active row.
**Key Fields:**
* `id` - Unique record identifier
* `dimAccountCode` - Surrogate key for the account version
* `accountCode` - Stable business key of the account
* `cpfCnpjCodeGuid` - Anonymized CPF/CNPJ identifier
* `personType` - Person type (F for individual, J for company)
* `dscSuitability` - Suitability profile description
* `startValidityDate` / `endValidityDate` - Validity window of this version
* `currentRegisterIndicator` - 1 for the current row, 0 otherwise
* `lastUpdate` - Last update timestamp (replication key)
Advisor dimension (SCD Type 2). Registry of the advisors linked to the partner; `account_advisor_relation` joins on `dimAdvisorCode`.
**Key Fields:**
* `id` - Unique record identifier
* `dimAdvisorCode` - Surrogate key for the advisor version
* `advisorCode` - Stable business key of the advisor
* `advisorName` / `advisorEmail` / `username` / `cpfCode` - Advisor identification
* `situation` - Advisor situation/status
* `master` - Master (parent) advisor identifier
* `xpEntryDate` / `xpExitDate` - Dates the advisor joined/left XP
* `validityStartDate` / `validityEndDate` - Validity window of this version
* `currentRegister` - Whether this is the current row
* `lastUpdate` - Last update timestamp (replication key)
Office channel dimension (SCD Type 2), describing the office and its hierarchy.
**Key Fields:**
* `id` - Unique record identifier
* `dimOfficeChannelCode` - Office channel surrogate key
* `officeCode` / `officeName` / `officeFantasyName` - Office identification
* `city` / `state` / `neighborhood` - Location
* `masterAdvisorCode` - Master advisor code
* `headOfficeCode` / `headOfficeName` - Head office
* `validityStartDate` / `validityEndDate` - Validity window
* `currentRegister` - 1 for the current row, 0 otherwise
* `lastUpdate` - Last update timestamp (replication key)
Product dimension (SCD Type 2) with classification, issuer, and yield attributes.
**Key Fields:**
* `id` - Unique record identifier
* `dimProductCode` - Product surrogate key
* `assetCode` / `assetName` - Asset identification
* `productClassficationL0` to `productClassficationL5` - Classification levels (key spelling matches the API)
* `isinCode` / `cnpjCode` / `cetselCode` - External identifiers
* `issuerName` / `managerName` / `strategy` - Issuer and management
* `productType` - Product type (DB, LCI, LCA, LC, LF, LIG, and others)
* `yield` / `index` / `dealType` - Yield attributes
* `lastUpdate` - Last update timestamp (replication key)
Movement type dimension.
**Key Fields:**
* `id` - Unique record identifier
* `dimMovementTypeCode` - Movement type surrogate key
* `movementTypeCode` - Movement type code
* `movementTypeDescription` - Movement type description
* `lastUpdate` - Last update timestamp (replication key)
Financial institution dimension.
**Key Fields:**
* `id` - Unique record identifier
* `dimFinancialInstitutionCode` - Financial institution surrogate key
* `financialInstitutionCode` / `financialInstitutionName` - Institution identification
* `categoryName` - Category
* `lastUpdate` - Last update timestamp (replication key)
Calendar dimension (loaded full). Provides date attributes and business/trading-day flags following the B3 calendar.
**Key Fields:**
* `id` - Unique record identifier
* `dimTimeCode` - Time key (YYYYMMDD)
* `date` - Calendar date
* `yearNumber` / `monthNumber` / `dayNumber` - Date parts
* `quarterNumber` / `weekOfTheYearNumber` - Period attributes
* `businessDay` / `tradingDay` - 1 if it is a business/trading day, 0 otherwise
* `nextTradingDate` - Next trading date
Media dimension. `additionalFields` carries technical metadata as a JSON string.
**Key Fields:**
* `id` - Unique record identifier
* `codConta` - Account code
* `marca` - Brand
* `device` - Device
* `baseUrl` - Base URL
* `additionalFields` - Additional technical metadata (JSON string)
* `lastUpdate` - Last update timestamp (replication key)
Fact table relating accounts to advisors over time.
**Key Fields:**
* `id` - Unique record identifier
* `dimAccountCode` / `accountCode` - Account references
* `dimAdvisorCode` / `advisorCode` - Advisor references
* `dimOfficeChannelCode` - Office channel reference
* `date` - Relation reference date
* `dimTimeCode` - Time key (YYYYMMDD, replication key)
* `lastUpdate` - Last update timestamp
Fact table of inflows and movements.
**Key Fields:**
* `id` - Unique record identifier
* `movementCode` - Movement code
* `movementNatureCode` - Movement nature
* `movementAmount` / `movementValue` - Quantity and value
* `dimAccountCode` / `dimProductCode` / `dimAdvisorCode` - Dimension references
* `dimFinancialInstitutionalCode` - Financial institution reference
* `dimMovementTypeCode` - Movement type reference
* `dimTimeCode` - Time key (YYYYMMDD, replication key)
* `lastUpdate` - Last update timestamp
Fact table of daily assets under custody by account and product.
**Key Fields:**
* `id` - Unique record identifier
* `dimAccountCode` / `dimProductCode` - Account and product references
* `dimOfficeChannelCode` / `dimAdvisorCode` - Office and advisor references
* `positionAmount` - Position quantity
* `positionValue` - Position value (assets under custody)
* `termDueDate` - Term due date
* `dimTimeCode` - Time key (YYYYMMDD, replication key)
* `lastUpdate` - Last update timestamp
Fact table of active customers per day.
**Key Fields:**
* `id` - Unique record identifier
* `dimAccountCode` - Account reference
* `accountQuantity` - Number of accounts
* `dimOfficeChannelCode` / `dimAdvisorCode` - Office and advisor references
* `operatedStockExchange` - Whether the client traded equities in the last 30 days
* `dimTimeCode` - Time key (YYYYMMDD, replication key)
* `lastUpdate` - Last update timestamp
Analytical stream combining client attributes with monthly revenue, capture, and net-position metrics.
**Key Fields:**
* `id` - Unique record identifier
* `accountCode` / `advisorCode` / `headOfficeCode` - Identification
* `segment` / `segmentClient` / `dscSuitability` - Client profile
* `status` / `activatedInM` / `churnedInM` - Lifecycle
* `financialApplications` / `revenueInMonth` - Balances and revenue
* `grossCaptureInMonth` / `redemptionInMonth` / `netCaptureInMonth` - Capture metrics
* `netInMonth` and related `net*` fields - Net positions by product class
* `positionDate` - Position date (replication key)
Control stream (full snapshot). Reports, per resource, the reference date and the processing window. Use `maximumProcessingDate` to know how current each resource is.
**Key Fields:**
* `tableName` - Name of the reprocessed resource
* `referenceDate` - Reference date of the data
* `typeProcessing` - Processing type (FULL or INCREMENTAL)
* `minimumProcessingDate` / `maximumProcessingDate` - Processing window