Skip to main content
Clara is a corporate card and spend management platform for companies in Brazil, Mexico and Colombia. This connector uses the Clara API to bring your company’s card transactions, cards, users, billing statements, reimbursements, labels, groups and locations to the Catalog. For Brazilian accounts it also brings the Clara digital account: PIX, TED and bill movements, the available balance and the Pix payments made through Clara.
The connector only reads data. It never creates, changes, locks or pays anything in Clara.

​
Prerequisites

Clara gives API access through an API project that your team creates in the Clara dashboard. API access starts on Clara’s Pro plan (the Free plan only has a one-time trial of 500 calls). If you have never used the API, ask your Clara Customer Success Manager to enable it.
  1. In the Clara dashboard, open Integrations > Clara API > Project credentials for your country:
    • Brazil: brasil.clara.com/settings/integrations/clara-api
    • Mexico: app.clara.cc/settings/integrations/clara-api
    • Colombia: colombia.clara.com/settings/integrations/clara-api
  2. Click Create project, give it a name (for example “Nekt”), choose the validity (up to 360 days) and, under Permissions to read, select everything you want to extract: cards, transactions, users, billing statements, reimbursements and, in Brazil, the digital account. No write permission is needed.
  3. Download the three files Clara offers: the public key (certificate), the private key and the client credentials JSON (with the Client ID and Client Secret).
Clara shows these files only once, when the project is created. Keep them in a safe place. If you lose them, create a new project.
Clara API projects expire at the end of the validity you chose (at most 360 days). Before that date, create a new project and update the four credentials in the source settings. Nekt warns you in the run log 30 days before the certificate expires, and the extraction stops with a clear message once it has expired.

​
Configuring Clara as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Clara option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

The following configurations are available:
  • Country: the country of your Clara account (brazil, mexico or colombia). The project credentials only work in the country where they were created.
  • Environment: production for your real data. sandbox is Clara’s test environment, with separate credentials you request from Clara’s integration team.
  • Client ID and Client Secret: from the client credentials JSON file of your API project.
  • Certificate (public key file): open the public key file in a text editor and paste all of its content, from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
  • Private key: paste all of the content of the private key file, from -----BEGIN ... PRIVATE KEY----- to -----END ... PRIVATE KEY-----.
  • Start date: the first day of transactions, digital account movements, Pix payments and reimbursements to extract.
Advanced settings:
  • Group company tax IDs: only for Clara accounts that manage a group of companies (a holding). List the tax IDs (CNPJ in Brazil) of the companies to extract, one per item. Each company is read separately and identified in the company_tax_identifier column of every table. Leave it empty to extract the company of the API project.
  • Private key password: only if your private key file is password-protected. The key Clara provides normally has no password.
  • Lookback days (default 2): how many days before the last day read each run reads again. Clara can take up to 2 business days to confirm a card transaction, so this catches late changes.
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.
Tip: The stream can be found more easily by typing its name.
If your company does not use the Clara digital account, do not select Digital Account Transactions, Digital Account Balance and Pix Payments. They only exist for Brazilian accounts with a digital account. If you select them anyway, Nekt skips them on each run (their tables are not created or changed) and the run log shows a warning asking you to unselect them. 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. A daily trigger is a good fit: every request counts against your Clara plan’s monthly API allowance (2,000 calls a month on the Pro plan), and each run tells you in its log how many requests it made. 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. A full sync reads everything again since the start date, so it uses more of the monthly API allowance.
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

​
Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description. Every table has a company_tax_identifier column: the tax ID of the group company the row belongs to when Group company tax IDs is set, and empty otherwise.
Corporate card transactions. Incremental by last_update_date: each run reads the transactions changed since a few days before the last run (see Lookback days), so status changes (for example from pre-authorized to authorized) are updated.Identification:
  • uuid - Unique identifier of the transaction (primary key, with company_tax_identifier)
  • type - PURCHASE, REFUND, FEE, CREDIT or PAYMENT
  • transaction_label - Label of the transaction as shown in Clara
  • status / status_description - NOTIFICATION, PRE_AUTHORIZED, AUTHORIZED, REJECTED or SYSTEM_TRANSACTION
  • authorization_number - Card network authorization number
  • comment - Comment added to the transaction
Amounts:
  • amount / currency - Amount in the billing currency (decimal units, not cents)
  • original_amount / original_currency - Amount in the original currency of the purchase
Dates:
  • operation_date - Purchase date
  • accounting_date - Accounting (posting) date
  • last_update_date - Date of the last change (replication key)
Merchant, card and cardholder:
  • merchant_name / merchant_category / merchant_category_code / merchant_mcc - Merchant and its category
  • card_uuid / card_last_four_digits / card_masked_pan - Card used
  • user_uuid / user_name / user_full_name / user_username / user_email - Cardholder
Statement and accounting:
  • billing_statement_uuid / billing_statement_start_date / billing_statement_end_date / billing_statement_status - Billing statement of the transaction. billing_statement_status is the status when the transaction last changed and is not updated when the statement closes: for the current status, join billing_statement_uuid with uuid in Billing Statements
  • accounting_status - NEEDS_REVIEW, READY_TO_EXPORT or EXPORTED
  • validation_status / validation_comment - Expense validation, when present
  • has_invoice / has_attachments / has_extracted_documents - Whether the transaction has an invoice, receipts or extracted documents
  • installment / installment_number - Installment information, when the purchase is in installments
  • labels - Labels of the transaction (JSON)
  • accounting_fields - Accounting fields (JSON)
  • bank_concept - Bank concept, when present (JSON)
Cards of the company. The table is replaced on every run with the current list.
  • uuid - Unique identifier of the card (primary key, with company_tax_identifier)
  • alias - Name given to the card
  • status / status_description - Card status (for example ACTIVE, LOCKED, CANCELLED)
  • lock_code - Who locked the card, when locked
  • masked_pan - Masked card number (the full number is never extracted)
  • threshold / periodicity - Spending limit and how often it resets (DAILY, WEEKLY or MONTHLY)
  • type - Card product and format (for example MASTER_VIRTUAL, MASTER_CORPORATE)
  • user_uuid / user_name / user_full_name / user_username / user_email - Cardholder
Clara users. The table is replaced on every run with the current list.
  • uuid - Unique identifier of the user (primary key, with company_tax_identifier)
  • full_name / name / last_name - Name of the user
  • email / mobile_phone - Contact
  • tax_identifier - Personal tax ID of the user (CPF in Brazil)
  • role - EMPLOYEE, MANAGER, COMPANY_OWNER or BOOKKEEPER
  • status / status_description - Status of the user
  • erp_id - Identifier of the user in your ERP
  • created_at - When the user was created
  • manager_uuid / manager_full_name / manager_email - Manager of the user
  • location_uuid / location_name - Location (cost center) of the user
  • groups - Groups of the user (JSON)
  • cards - Cards of the user, with masked numbers only (JSON)
Monthly billing statements. The table is replaced on every run with the current list.
  • uuid - Unique identifier of the statement (primary key, with company_tax_identifier)
  • status - OPEN (current cycle) or CLOSED
  • statement_start_date / statement_end_date - Statement period
  • statement_date / payment_limit_date - Issue date and due date, when sent
  • currency / total_amount - Currency and total of the statement
  • current_balance / required_payment / paid_amount / unpaid - Payment information, when sent
  • generated_at - When the statement was generated
Out-of-pocket expense reimbursements. Incremental by last_update_date.
  • uuid - Unique identifier of the reimbursement (primary key, with company_tax_identifier)
  • description - Description of the expense
  • status / status_comment - PENDING, APPROVED, SENT_TO_PAY, PAYMENT_IN_PROGRESS, PAID, REJECTED, FINANCE_REJECTED or CANCELLED, and the last comment
  • amount / currency - Amount of the expense
  • request_creation_date / expense_date / final_approval_date / payment_date - Lifecycle dates
  • last_update_date - Date of the last change (replication key)
  • requester_uuid / requester_name / requester_email - Employee who requested it
  • merchant_name / merchant_description / merchant_category / merchant_category_code / merchant_country_code - Merchant
  • payment_method / payment_method_note / marked_as_paid_by - How it was paid
  • labels / groups / locations - Classification (JSON)
  • attachments - Attached files, names only (JSON)
Brazil only. Movements of the Clara digital account. Incremental by transaction_date_time.
  • id - Unique identifier of the movement (primary key, with company_tax_identifier)
  • end_to_end_id - PIX end-to-end identifier
  • transaction_date_time - Date and time of the movement, in UTC (replication key)
  • transaction_date - Date of the movement (legacy field)
  • amount - Amount in BRL
  • method - PIX, TED, Bill, Transfer or Undefined
  • type - Description of the movement (for example Transfer sent, Deposit in account, Reversal of sent transfer)
  • description / digitable_line - Description and digitable line, mostly for bills
  • source_name / source_tax_id / source_institution - Origin party
  • beneficiary_name / beneficiary_tax_id / beneficiary_institution - Destination party
  • charges - Bill fees: discount, fee, interest and total (JSON)
  • original_transaction_id / original_transaction - Original movement, when the row is a reversal
Brazil only. One row with the balance as of the last run. The table is replaced on every run.
  • checking_account_available - Available balance of the checking account in BRL
  • checking_account_available_cents - The same balance as Clara sends it, in cents
  • collateral_account_available - Available balance of the collateral account in BRL (0 when there is none)
  • extracted_at - When the balance was read
Brazil only. Pix payments made through Clara’s payments API (accounts payable). Incremental by creation_date. Payments that are still scheduled or in process are followed on every run with one extra request for the whole list of open payments, plus one request for each payment whose status changed (up to 20 per run; the rest on the next run), until they reach a final status (PAID, FAILED or CANCELLED).
  • external_id - Identifier of the payment (primary key, with company_tax_identifier)
  • status - IN_PROCESS, SCHEDULED, PAID, FAILED or CANCELLED
  • amount / currency_code / payment_method - Amount in BRL and method (PIX)
  • description - Description of the payment
  • beneficiary_name / beneficiary_document_number - Beneficiary and its CPF (masked) or CNPJ
  • beneficiary_bank / beneficiary_bank_name / beneficiary_account_type / beneficiary_account_number / beneficiary_branch - Beneficiary account, for payments made with bank details
  • pix_end_to_end_id - Pix end-to-end identifier, after settlement
  • error_code / error_message - Why a payment failed
  • creation_date - When the payment was created (replication key)
  • payment_date - Settlement date
Reference lists. Each table is replaced on every run with the current list.
  • uuid - Unique identifier (primary key, with company_tax_identifier)
  • name - Name
  • description - Description, when set
  • code - Code, when set (locations use it to link ERP or HR systems)
  • status - Status (for example ACTIVE or INACTIVE)

​
Limitations

  • API allowance: every request, including authentication, counts against your Clara plan’s monthly API allowance (2,000 calls a month on the Pro plan). A daily run of all tables for one company uses about 17 requests (around 510 a month) when each list fits in one page of 100 rows; larger lists add one request per 100 rows, and each company listed in Group company tax IDs costs the same again. The first run since an old start date uses more. You can follow the consumption in Clara under Integrations > Clara API > API Insights. If Clara keeps answering with its request-limit error (the monthly allowance used up, or another application using the same API project at the same time), the run stops the remaining tables at once with a message saying so, without spending more requests.
  • Receipts, invoices and extracted documents of each transaction are not extracted: Clara serves them one transaction at a time, with download links that expire in 12 hours, which would use one request per transaction. The has_attachments, has_invoice and has_extracted_documents columns show which transactions have them.
  • CFDI invoices (Mexico only), virtual card numbers for B2B purchases (VCN) and webhook settings are not extracted.
  • Full card numbers and CVV are never extracted; only masked numbers.
  • If Clara refuses a stream (missing permission in the API project), that stream fails and the run log names it; the other selected streams are still extracted. Add the read permission to the project in Clara, or unselect the stream.
  • If most of what Clara returns for Transactions or Reimbursements is older than the requested dates (Clara stopped applying the date filter, which would make every run read the whole history), the stream stops with a message instead of spending the API allowance. A few older records are normal and are loaded. Contact Nekt support if you see the message.