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.
  • Client Certificate (PEM): The mTLS client certificate, in PEM format. If this value also contains the private key, leave the private key field empty.
  • Private Key (PEM): The private key matching the certificate, in PEM format. Leave empty if the certificate already includes the key.
  • Private Key Passphrase: The passphrase to decrypt the private key, if it is encrypted.
  • Partner Name: An identifier for your office, used in the request User-Agent.
  • Start Date: The earliest record date to sync for incremental streams.
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.
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)
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