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 per-customer streams (balances, consolidated position, investment account statement, positions by date and operations) to the customers you list. Leave it empty to read every account whose registry row is current. Each customer costs at least one API request per per-customer stream, so this is how you pilot or cap a source that runs several times a day.
  • Per-customer history start date (advanced): The first day read by the investment account statement, positions by date and operations streams on their first sync and on a full sync. Leave it empty to start 15 days back. It only matters before a stream’s first run: changing it later does not reload older days. Each 15-day period costs one API request per customer per stream, so a long history is loaded over several runs.
  • Max windows per run (advanced): How many 15-day periods the investment account statement, positions by date and operations streams read in each run (default 2). A daily run needs only one; a longer history is loaded a few periods per run, each run continuing where the previous one stopped.
  • Excluded customer codes (advanced): Customers that the consolidated position, investment account statement, positions by date and operations streams never request. Use it for a customer XP rejects on every run: the run’s error message lists those customers. Write each code exactly as XP returns it and as the error lists it, since codes are compared as text (001234 does not match 1234). The balance streams ignore it.
  • Operations product types (advanced): The product types requested by the operations stream. Keep the default unless XP rejects it.
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. Four more per-customer streams keep history instead of a single snapshot: Consolidated Position, Investment Account Statement, Positions by Date and Operations. They are not selected by default, because each one adds at least one API request per customer to every run: with about 6,000 customers, that is roughly 20 to 25 minutes per stream per run. Consolidated Position and the statement are current-day data (D0). Positions by Date and Operations are published by XP three business days later (D-3), so running them more than once a day brings no new data.
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
The customer’s consolidated position for the day (D0): totals, cash and projected balances, declared wealth and the position in each product type. One row per customer per day: every run on the same day updates that day’s row, and earlier days stay in the table.Key Fields:
  • customerCode - XP code of the customer (primary key)
  • positionDate - Day of the position (primary key)
  • patrimonioTotal / patrimonioTotalLiquido / investimentos / valorDisponivel - Totals
  • financeiro* - Cash, projected balances (D+1 to D+3), collateral and pending redemptions
  • valorBensMoveis / valorBensImoveis / valorAplicacoesFinanceiras / totalPatrimonioDeclarado - Wealth declared by the customer
  • produtos - Position in each product type (stocks, funds, fixed income, treasury, pension, COE and others) with its items, as a JSON string
  • dadoAtualizado / dataAtualizacao / atualizeEm - Whether XP reports the data as final, when it was last updated and when XP suggests reading it again
  • extractedAt - When the position was read (replication key)
Entries of the customer’s investment account statement (D0). One row per entry.Key Fields:
  • customerCode - XP code of the customer (primary key)
  • entryNumber - Identifier of the entry (primary key)
  • entryDate - Day of the entry (replication key)
  • referenceDate / settlementDate - Reference and settlement dates
  • value - Amount of the entry (negative for debits)
  • balance - Account balance after the entry
  • description / historicalCode - What the entry is
  • isFuture - Whether the entry is scheduled for a future date
  • brand / tradingAccount / whiteLabel - Account the statement belongs to
  • lastUpdate - When XP last updated the entry
Daily position of each asset the customer holds, with its return (D-3). One row per asset per day, for every product type: COE, funds, fixed income, checking account, pension funds, repo, treasury, stocks and traded funds.Key Fields:
  • customerCode - XP code of the customer (primary key)
  • positionKey - Identifier of the position created by Nekt, since XP sends none (primary key)
  • category - Product type
  • positionDate - Day of the position (replication key)
  • assetId / asset / isin / fundCNPJ / cetipSelicCode - Asset identification
  • openingQuantity / closingQuantity / openingValue / closingValue / closingNetValue - Quantities and values at the opening and close of the day
  • yield / previousYield / accumulatedYield / profitAndLoss - Return of the position
  • incomeTax / iof - Taxes
  • details - Every field XP sent for the position, as a JSON string
Operations made by the customer, such as applications, redemptions, purchases and sales (D-3). One row per operation, for funds, fixed income, pension funds, treasury, COE, stocks, traded funds and repo.Key Fields:
  • customerCode - XP code of the customer (primary key)
  • operationKey - Identifier of the operation created by Nekt, since XP sends none (primary key)
  • category - Product type
  • eventDate - Day of the operation (replication key)
  • asset / assetId / isin / fundCNPJ - Asset identification
  • type / eventType / operationType - Kind of operation
  • quantity / unitPrice / grossValue / netValue - Quantity and values
  • incomeTax / iof - Taxes
  • settlementDate - Settlement date
  • details - Every field XP sent for the operation, as a JSON string

​
Implementation Notes

​
Authentication Retries

The XP gateway intermittently returns 401 Unauthorized errors for requests that have valid credentials. To prevent syncs from failing due to this gateway instability, the connector automatically intercepts 401 responses, discards the cached OAuth token, requests a fresh one, and retries the request. A sync will only fail with an authentication error if the 401 response persists across every retry attempt, which indicates that the credentials were genuinely rejected or have expired.

​
Per-Customer Streams with History

  • Cost and schedule: these streams read one customer at a time and share XP’s limits with every other XP source of the same subscription: 300 requests per minute, and at most 20 GB of data transferred every 12 hours. Schedule sources so their runs do not overlap, and keep Positions by Date and Operations, which XP publishes three business days late, on a daily trigger.
  • How much history: the Investment Account Statement, Positions by Date and Operations streams read 15-day periods, one period at a time for all customers, and remember how far they got after each complete period. Each run starts some days before that point, to pick up late postings and corrections: 7 days for the statement, and 13 days for Positions by Date and Operations, since XP publishes them three business days late, which around the year-end holidays means a week or more. Each run reads at most Max windows per run periods. Their first run starts at Per-customer history start date, or 15 days back. Because each run starts again a few days before where the previous one stopped, the periods overlap: with the default of 2 periods per run, each run moves forward about 16 days for Positions by Date and Operations and about 23 days for the statement. One year of history is therefore loaded over about 23 runs, roughly 250,000 requests per stream for 6,000 customers (about 16 runs for the statement). A customer that joins your office later gets data from one to two weeks back on. A day that XP publishes more than about two weeks late is not read again.
  • Avoid full syncs on these streams: a full sync rebuilds the table starting at Per-customer history start date (or 15 days back), reading the whole period in a single run, so older days are removed. For Consolidated Position, a full sync keeps only today’s position and removes every earlier day. The run log warns about both. Do not schedule an Additional Full Sync for them.
  • Errors are not skipped: the only answer that skips a customer is XP saying the customer does not belong to your office; those customers are listed in the run log. Any other error for a customer (400 Bad Request or 404 Not Found) is data XP did not send, so the run reads the rest of the period and then fails, and the next run reads that period again. If ten customers in a row get such an error, the run stops right away, since the request itself is likely wrong. If XP rejects the same customer on every run, add it to Excluded customer codes so the other customers keep loading.