> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Upsert records bulk
> Imports records in an existing table via an import.
Create new records or update existing ones.
# How to use it
## Create your data table
To push data to a data table, you will need to setup first the table inside Qobra [here](https://app.qobra.co/objects/fields). You must select the Public API integration in the first step of creating a table. After creating the table you will need to set up all the fields you will use later.
If you try editing your data table, you’ll find:
* the `table-api-name`, that you can edit, to identify your data table
* the `id-field-api-name`, that you can edit if needed
* the `name-field-api-name`, that you can edit if needed
On this page, you will also find each of your data table fields api keys (`field-api-key`). You can edit them if needed.
## Variable api keys
This endpoint is based on dynamic fields. This mean that all annotations
that look like ``, will have to or will be replaced by their
actual API keys.
## Best practices for large imports
We recommend splitting large imports into smaller batches (for example 1,000 to 5,000 records per request).
Sending very large payloads in a single request can lead to network timeouts or failed imports.
Sending very small payloads (for example, one or a few records) per request is discouraged, as it may quickly hit the API rate limit (80 requests per second across all endpoints) and significantly slow down ingestion.
For full resynchronizations, you can combine batching with the all and debounce query parameters.
## Trouble shooting
When trouble shooting a webhook import, first check you imports are present in Qobra’s import page [here](https://app.qobra.co/objects/imports).
* if your imports do not appear in the list of previous imports (after refreshing the page), check the authentication
* if your import is in warning, you’ll see the records which did not import, with the error’s detail
* if your import seems successful, but data in your data table is not updated, your fields api name must mismatch the ones parameterized in Qobra.
## OpenAPI
````yaml post /v1/tables/{data_table_key}/records/bulk
openapi: 3.0.2
info:
version: 1.0.0
title: Qobra API
description: API documentation for Qobra
servers:
- url: https://api.qobra.co
description: API
security: []
paths:
/v1/tables/{data_table_key}/records/bulk:
post:
tags:
- public_api
- v1
- tables
summary: Upsert records bulk
description: Imports records in an existing table via an import.
operationId: POST_/v1/tables/(data_table_key)/records/bulk
parameters:
- name: data_table_key
in: path
required: true
schema:
type: string
description: Used to identify the data table
- name: all
in: query
schema:
title: All
description: >-
Optional: if all is true, the request will delete all the data
table’s content, before doing the import
default: false
type: boolean
required: false
- name: debounce
in: query
schema:
title: Debounce
description: >-
Optional (minimum:0): debounce is the number of seconds we wait
before launching imports. This query parameter is used in
conjunction with the all query parameter. If you want to push a
large number of records, but delete the data tables records
before, this debounce system will enable you to split this large
amount in several requests. For instance, if you have 300k records
to push, you can set a the debounce query parameter to 15 minutes
and split your synchronisation in 60 requests of 5k records each.
For large imports, we recommend combining debounce with batched
requests. See the Best practices for large imports section above
for recommended batch sizes and ingestion patterns.
default: 0
type: integer
required: false
- name: keep_overrides
in: query
schema:
title: Keep Overrides
description: >-
Optional: When set to true it will keep the manual overrides made
in the targeted data table.
default: false
type: boolean
required: false
requestBody:
description: >-
The body is a json list of records you want to push to Qobra. Each
record in the list should be an object containing the following keys,
and values associated
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RecordsImportIngestionPostModel'
examples:
record-import-body:
$ref: '#/components/examples/RecordsImportIngestionPostModelExample'
responses:
'200':
description: Success operation
content:
application/json:
schema:
$ref: '#/components/schemas/RecordsImportsModelResponseSuccess'
examples:
ingestion-success:
$ref: >-
#/components/examples/RecordsImportsModelResponseSuccessExample
security:
- api_key: []
components:
schemas:
RecordsImportIngestionPostModel:
properties:
items:
description: Array containing all the records you want to import.
type: array
items:
$ref: '#/components/schemas/RecordsImportIngestionModel'
title: RecordsImportIngestionPostModel
RecordsImportsModelResponseSuccess:
type: object
properties:
import_id:
title: Import Id
type: string
format: ObjectId
description: unique identifier of the import you created
objects_imported:
title: Objects Imported
type: integer
description: number of records your request contained
required:
- import_id
- objects_imported
title: RecordsImportsModelResponse
RecordsImportIngestionModel:
type: object
properties:
:
description: Record unique identifier value.
type: string
:
description: Record name value.
type: string
:
description: Field string value.
type: string
:
description: Field checkbox value.
type: boolean
:
description: Field number value.
type: number
:
description: Field percentage value.
type: number
:
description: >-
ISO Formatted Date UTC or with explicit timezone (YYYY-MM-DD or
YYYY-MM-DDTHH:MM:SS±HH:MM).
type: string
:
description: >-
Field user value as email or a string, depending of the user
matching key defined in the data table settings.
type: string
:
description: Field picklist key value.
type: string
:
description: Field multipicklist key values, semicolon separated.
type: string
:
description: Field amount value.
type: number
_currency:
$ref: '#/components/schemas/CurrencyCode'
deleted:
description: Input true if the record should be deleted after import.
type: boolean
required:
-
-
-
-
-
-
- _currency
title: RecordsImportIngestionModel
CurrencyCode:
description: Allowed currency codes.
type: string
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BOV
- BRL
- BSD
- BTN
- BWP
- BYR
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNY
- COP
- COU
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- IQD
- IRR
- ISK
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LTL
- LVL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SLL
- SOS
- SRD
- STD
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYI
- UYU
- UZS
- VEF
- VND
- VUV
- WST
- XAG
- XAU
- XCD
- XPD
- XPT
- XSU
- YER
- ZAR
- ZMK
- ZWL
title: CurrencyCode
examples:
RecordsImportIngestionPostModelExample:
value:
- id: 6545110915808dbcc34531ef
name: Great opportunity
owner_id: user@company.fr
close_date: '2024-06-25T09:58:32Z'
product: Product A
amount: 4000
amount_currency: EUR
deleted: false
deal_types: New Business;Existing Business
- ...
RecordsImportsModelResponseSuccessExample:
value:
import_id: QfejsQZ6mpOVHT5Tt1SdNLPZ
objects_imported: 1
securitySchemes:
api_key:
type: apiKey
name: X-API-Key
in: header
````