Skip to main content
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 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.
  • Customer Codes (advanced): Restricts the balance streams to the customers you list. Leave it empty to read every account whose registry row is current. Each customer costs one API request per balance stream, so this is how you pilot or cap a source that runs several times a day.
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, 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.
  • Determine when to execute an 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 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, 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. They carry data as of D-1 (the previous day) and are updated only on B3 business days. The balance streams work differently: they read the customer’s balance as it stands at the moment of the sync (D0). XP exposes them one customer at a time, so the source makes one API request per customer on every run, and the balance is stored as a snapshot — each run refreshes the customer’s row instead of appending history, with extractedAt recording when the snapshot was taken. Because XP allows 300 requests per minute per subscription across all of its APIs, how long a run takes grows with the size of your customer base; use the Customer Codes advanced setting to restrict a source to a subset of customers.
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
Current balance of the customer’s digital account, read live at sync time (D0). One row per customer, refreshed on every run.Key Fields:
  • customerCode - XP code of the customer the balance belongs to (primary key)
  • agency - Identifier of the digital account’s branch
  • tradingAccount - Identifier of the digital account
  • amount - Amount available for transactions
  • blockedAmount - Amount blocked and unavailable for use
  • amountWithOverdraft - Amount available including the overdraft limit
  • overdraftLimit / overdraftAvailable / overdraftConsumed - Overdraft granted, still available, and already used
  • lastChangeDate - When the balance last changed, as reported by XP
  • extractedAt - When this snapshot was read from the API
Current balance of the customer’s investment account, read live at sync time (D0). One row per customer, refreshed on every run.Key Fields:
  • customerCode - XP code of the customer the balance belongs to (primary key)
  • brand - Brand of the investment account
  • tradingAccount - Number of the trading account
  • whiteLabel - White label identifier of the account
  • amount - Balance available in the investment account
  • lastUpdate - When the balance was last updated, as reported by XP
  • extractedAt - When this snapshot was read from the API