Post data
How to import data to OpenDataBio using the API
15 minute read
Importing data
- The OpenDataBio-R package is a client for this API and lets you import, download and update data from R objects.
- Examples of importing from R are here;
- Data can be imported via the web interface using spreadsheets, where the column names are the POST parameters listed on this page
- An authentication token is required for all POST requests
- Imports may run as background UserJobs. A completed job may still contain per-record warnings or errors; inspect its structured results.
The former activities import endpoint has been removed. Use the
identification-histories endpoint for biological identification history. The
application activity log is an audit trail and is not an importable biological
history.
Structured custom data in the notes field
The notes field of any model is for plain text or a text formatted as a JSON object containing structured data. Json allows you to store custom structured data in any model that has the notes field. For example, you may want to store secondary fields from source datasets during import, or any additional data not provided by the OpenDataBio database structure. This data is not validated by OpenDataBio and the standardization of tags and values is up to you. Json notes will be imported and exported as JSON text and will be presented in the interface as a formatted table; URLs in your Json will be presented as links in this table.
POST endpoints
Quick links
- bibreferences
- biocollections
- individuals
- individual-locations
- locations
- locations-validation
- measurements
- media
- persons
- taxons
- traits
- vernaculars
- vouchers
- datasets
- identification-histories
bibreferences (POST)
Bibliographic references (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
bibtex | No | BibTeX formatted reference string. (Provide doi or bibtex.) | @article{mykey,...} |
doi | No | DOI number or URL. (Provide doi or bibtex.) | 10.1234/abcd.2020.1 |
biocollections (POST)
Biocollections (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
acronym | Yes | Biocollection acronym. | INPA |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
individuals (POST)
Individuals (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
altitude | No | Elevation in meters. | 75 |
angle | No | Azimuth from reference point, in degrees. | 45 |
biocollection | No | Biocollection id, name or acronym. | INPA |
biocollection_number | No | Catalogue number/code inside the biocollection. | 12345 |
biocollection_type | No | Nomenclatural type code or name. | Holotype or 2 |
collector | Yes | Collector(s) id, abbreviation, name or email. Use | or ; to separate multiple people; first is main collector. | J.Silva|M.Costa |
dataset | Yes | Dataset id or acronym. | 3 or FOREST1 |
date | Yes | Date (YYYY-MM-DD) or incomplete date (e.g. 1888-05-NA) or array with year/month/day. (At least the year must be provided.) | 2024-05-20 or {\"year\":1888,\"month\":5} |
distance | No | Distance from reference point in meters. | 12.5 |
identification_based_on_biocollection | No | Biocollection name/id used as reference for identification. | INPA |
identification_based_on_biocollection_number | No | CatalogNumber in the reference biocollection | 8765 |
identification_date | No | Identification date (full or incomplete). | 2023-06-NA |
identification_individual | No | ID/organismID of another individual that provides the taxonomic identification for the individual’s record | 3245 or REC-123 |
identification_notes | No | Notes for the identification. | Checked with microscope |
identifier | No | Person(s) responsible for identification; accept id, abbreviation, name or email; separate multiple with | or ;. Required when taxon is informed. Use identifier=collector to use the collector value explicitly provided in the same record, or identifier=keep in updates to preserve the existing identifier. | Costa, A.|Lima, B. or 1|2|3 or collector or keep |
latitude | No | Latitude in decimal degrees (negative for south). (Required when location is not provided.) | -3.101 |
location | No | Location id or name. (Required when latitude/longitude are not provided.) | Parcela 25ha or 55 |
location_date_time | No | Date or date+time for the occurrence/location event. (Required when adding multiple locations or when different from individual date.) | 2023-08-14 12:30:00 |
location_notes | No | Notes for the occurrence/location entry. | Near trail marker 10 |
longitude | No | Longitude in decimal degrees (negative for west). (Required when location is not provided.) | -60.12 |
modifier | No | Identification modifier code/name (s.s.=1, s.l.=2, cf.=3, aff.=4, vel aff.=5). | 3 |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
tag | Yes | Individual tag/number/code. | A-1234 |
taxon | No | Taxon id or canonical full name list. | Licaria cannela or 456,789 |
x | No | Cartesian coordinate for individual within plot/transect, from origin | 10 |
y | No | Cartesian coordinate for individual within plot/transect. When transect, positive values for right-side and negative for left-side, from origin. | 5.1 |
individual-locations (POST)
Occurrences for individuals with multiple locations (GET lists, POST/PUT upserts).
| Parameter | Required | Description | Example |
|---|---|---|---|
altitude | No | Elevation in meters. | 75 |
angle | No | Azimuth from reference point, in degrees. | 45 |
distance | No | Distance from reference point in meters. | 12.5 |
individual | Yes | Individual id, uuid or organismID (fullname). | 4521 or 2ff0e884-3d33 |
latitude | No | Latitude in decimal degrees (negative for south). (Required when location is not provided.) | -3.101 |
location | No | Location id or name. (Required when latitude/longitude are not provided.) | Parcela 25ha or 55 |
location_date_time | Yes | Date or date+time for the occurrence/location event. | 2023-08-14 12:30:00 |
location_notes | No | Notes for the occurrence/location entry. | Near trail marker 10 |
longitude | No | Longitude in decimal degrees (negative for west). (Required when location is not provided.) | -60.12 |
x | No | Cartesian coordinate for individual within plot/transect, from origin | 10 |
y | No | Cartesian coordinate for individual within plot/transect. When transect, positive values for right-side and negative for left-side, from origin. | 5.1 |
locations (POST)
Locations (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
adm_level | Yes | Location administrative level code (e.g. 100=plot, 10=country). | 100 |
altitude | No | Elevation in meters. | 75 |
azimuth | No | Azimuth (degrees) used to build plot/transect geometry when location is a POINT. | 90 |
datum | No | Spatial datum/projection string. | EPSG:4326-WGS 84 |
geojson | No | Input-only GeoJSON Feature with geometry and at least name + adm_level properties. It is parsed into the location geometry and is not stored as a locations.geojson column. (Provide geojson, geom or lat+long.) | {\"type\":\"Feature\",\"properties\":{\"name\":\"Plot A\",\"adm_level\":100},\"geometry\":{...}} |
geom | No | WKT geometry (POINT, LINESTRING, POLYGON, MULTIPOLYGON). (Provide geojson, geom or lat+long.) | POLYGON((-60 -3,-60.1 -3,-60.1 -3.1,-60 -3.1,-60 -3)) |
ismarine | No | Flag to allow marine/offshore locations outside country polygons. | 1 |
lat | No | Latitude in decimal degrees (negative for south). (Provide geojson, geom or lat+long.) | -3.101 |
long | No | Longitude in decimal degrees (negative for west). (Provide geojson, geom or lat+long.) | -60.12 |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
parent | No | Parent id/name; for traits this is another trait export_name/id to define hierarchy. | woodDensity |
startx | No | Start X coordinate for subplot relative to parent plot. | 5.5 |
starty | No | Start Y coordinate for subplot relative to parent plot. | 10.0 |
x | No | X dimension for plots/transects | 100 |
y | No | Y dimension for plots or buffer for transects | 40 |
locations-validation (POST)
Validates coordinates against registered locations (POST).
| Parameter | Required | Description | Example |
|---|---|---|---|
latitude | Yes | Latitude in decimal degrees (negative for south). | -3.101 |
longitude | Yes | Longitude in decimal degrees (negative for west). | -60.12 |
measurements (POST)
Trait measurements (GET lists, POST creates/imports via ImportMeasurements job, PUT bulk updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
bibreference | No | Bibreference id or bibkey. | 34 or ducke1953 |
dataset | Yes | Dataset id/name where the measurement will be stored; falls back to authenticated user default dataset if omitted. | 3 or FOREST1 |
date | Yes | Measurement date; accepts YYYY-MM-DD, YYYY-MM, YYYY, or array/year-month-day fields (date_year/date_month/date_day). | 2024-05-10 or {\"year\":2024,\"month\":5} |
duplicated | No | Integer allowing repeated measurements on the same date/object; must be higher than existing duplicates. | 2 |
link_id | No | Required for LINK trait types: id of the linked object (e.g., Taxon id). (Required when trait type is Link.) | 55 |
location | No | Location id or name. | Parcela 25ha or 55 |
notes | No | Optional free text or JSON notes stored with the measurement. | {\"method\":\"caliper\"} |
object_id | Yes | Required. Id of the measured object (Individual, Location, Taxon, Voucher, Media). Alias: measured_id. | 4521 |
object_type | Yes | Required when not provided in header. Class basename or FQCN of the measured object (Individual, Location, Taxon, Voucher, Media). Alias: measured_type. | Individual |
parent_measurement | No | When trait depends on another measurement, provide the parent measurement id for the same object and date. | 3001 |
person | Yes | Person id, abbreviation, full name or email (supports lists with | or ;). | J.Silva|M.Costa |
trait_id | Yes | Required. Trait id or export_name to be measured (also accepts trait key “trait”). | DBH or 12 |
value | No | Input varies by trait type: QUANT_INTEGER (0) = integer number; QUANT_REAL (1) = decimal number with dot separator; CATEGORICAL or ORDINAL (2/4) = single category id or translated name; CATEGORICAL_MULTIPLE (3) = list of category ids/names separated by | ; or , (or an array); TEXT (5) = free text string; COLOR (6) = hex color like #A1B2C3 or #ABC; LINK (7) = send link_id pointing to the linked object (value may be blank or a numeric qualifier); SPECTRAL (8) = semicolon-separated numeric series whose length equals trait value_length; GENEBANK (9) = GenBank accession string (validated against NCBI). (Required unless trait type is Link.) | QUANT_REAL: 23.4 | CATEGORICAL: 15 or Dead | CATEGORICAL_MULTIPLE: 12;14 or Alternate;Opposite | SPECTRAL: 0.12;0.11;0.10 |
media (POST)
Media metadata (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
collector | No | Collector(s) id, abbreviation, name or email. Use | or ; to separate multiple people; first is main collector. | J.Silva|M.Costa |
dataset | No | Dataset id or acronym. | 3 or FOREST1 |
date | No | Date (YYYY-MM-DD) or incomplete date (e.g. 1888-05-NA) or array with year/month/day. | 2024-05-20 or {\"year\":1888,\"month\":5} |
filename | Yes | Exact media file name inside the ZIP when importing media. | IMG_0001.jpg |
latitude | No | Latitude in decimal degrees (negative for south). | -3.101 |
license | No | Public license code for media (CC0, CC-BY, CC-BY-SA, etc.). | CC-BY-SA |
location | No | Location id or name. | Parcela 25ha or 55 |
longitude | No | Longitude in decimal degrees (negative for west). | -60.12 |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
object_id | Yes | Id of object the media belongs to (Individual, Location, Taxon, Voucher). | 4521 |
object_type | Yes | The object type the media belongs to, one of Individual, Location, Taxon, or Voucher. | Individual |
project | No | Project id or acronym. | PDBFF or 2 |
tags | No | Tag ids or names list for media or filters (use | or ;). | flower|leaf |
title_en | No | Media title in English. | Leaf detail |
title_pt | No | Media title in Portuguese. | Detalhe da folha |
persons (POST)
People (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
abbreviation | No | Standard abbreviation for a person or biocollection. | Silva, J.B, Pilco, M.V. |
biocollection | No | Biocollection id, name or acronym. | INPA |
email | No | Email address. | user@example.org |
full_name | Yes | Person full name. | Joao Silva |
institution | No | Institution associated with a person. | INPA |
taxons (POST)
Taxonomic names (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
author | No | Optional authorship string for published names. It is commonly filled automatically by API. For unpublished names, keep author null and use author_id/person. | Nees |
author_id | No | Alternative to person for unpublished names. Required for unpublished names when person is not sent. (Required for unpublished names (or use person).) | 25 |
bibkey | No | Optional bibreference id or bibkey to resolve bibreference_id. For published names, API-derived bibliographic data may also populate the record. | ducke1953 or 34 |
bibreference | No | Bibreference id or bibkey. | 34 or ducke1953 |
enforceValid | No | Optional boolean override for published names. Use when you send valid=true and want to override an API result that marks the name as invalid and assigns a senior name. | 1 or true |
gbif | No | Optional GBIF id. For POST it is stored as informed; no API validation is required for this explicit value. | 28792 |
indexfungorum | No | Index Fungorum identifier for a taxon. | IF123456 |
ipni | No | Optional IPNI id. For POST it is stored as informed; no API validation is required for this explicit value. | 123456-1 |
level | No | Optional for published names because API lookup may define it. Required for unpublished names except when the validated name is a two-word binomial, which is imported as species. Accepts numeric rank code or rank name such as species/subspecies/clade. | 210 or species |
mobot | No | Optional Tropicos/MOBOT id. For POST it is stored as informed; no API validation is required for this explicit value. | 25509881 |
mycobank | No | Optional MycoBank id. For POST it is stored as informed; no API validation is required for this explicit value. | MB123456 |
name | Yes | Required taxon name. For published names, POST validates the name against external nomenclatural APIs and may normalize name, parent, rank, validity, senior_id, authorship, bibreference, and external ids. For unpublished names, inform author_id/person and parent; level is required unless the validated name is a two-word binomial, which is imported as species. | Ocotea guianensis or Inga sp. 1 |
parent | No | Optional for published names, required for unpublished names. Accepts parent id or scientific name. For published names, if the API finds a different parent, the informed parent is kept and a warning is logged. (Required for unpublished names.) | Ocotea or 120 |
parent_id | No | Parent id for hierarchical queries. | 210 |
parent_name | No | Alternative parent taxon name used by taxon imports and updates. | Ocotea |
person | No | Use for unpublished names only. Accepts person id, abbreviation, full name, or email; resolved to author_id. When present, the record is treated as unpublished and API lookup is not used. (Required for unpublished names (or use author_id).) | 25 or Pilco, M.V. |
senior | No | Accepted senior taxon id or name used when importing an invalid taxon. | Ocotea guianensis |
senior_id | No | Optional accepted-name taxon id used when the imported taxon is invalid. The senior taxon must already exist, must be valid, and must be published. | 345 |
valid | No | Optional boolean. When omitted on POST, validity is inferred from senior/senior_id or API result. Invalid names are allowed for both published and unpublished taxa. If you send valid=true for a published name and the API says the name is invalid, the import is rejected unless enforceValid=true is also sent. | 1 or 0 |
zoobank | No | Optional ZooBank id. For POST it is stored as informed; no API validation is required for this explicit value. | urn:lsid:zoobank.org:act:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
traits (POST)
Trait definitions (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
bibreference | No | Bibreference id or bibkey. | 34 or ducke1953 |
categories | No | Trait categories JSON list with lang/rank/name/description. (Required for categorical and ordinal traits.) | [{\"lang\":\"en\",\"rank\":1,\"name\":\"small\"}] |
description | Yes | Translatable description text. Accepts a plain string or a JSON map of language codes to descriptions. | {"en":"Tree height at breast height","pt-br":"Altura da árvore à altura do peito"} |
export_name | Yes | Unique export name for trait. | treeDbh,plantHeight |
link_type | No | Class name for Link trait target (e.g. Taxon). (Required for Link traits.) | Taxon |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
objects | Yes | Trait target objects (comma separated). | Individual,Voucher |
parent | No | Parent trait id or export_name; when set, measurements of this trait must also include a measurement for the parent trait. | woodDensity |
range_max | No | Maximum allowed numeric value for quantitative traits. | 999.9 |
range_min | No | Minimum allowed numeric value for quantitative traits. | 0.01 |
tags | No | Tag ids or names list for media or filters (use | or ;). | flower|leaf |
type | Yes | Generic type parameter (trait type code or vernacular type such as use/generic/etimology). | use or 10 |
unit | No | (Required for quantitative and spectral traits.) | — |
value_length | No | Number of values for spectral trait types. (Required for spectral traits.) | 1024 |
wavenumber_max | No | Maximum wavenumber for spectral traits. (Required for spectral traits.) | 25000 |
wavenumber_min | No | Minimum wavenumber for spectral traits. (Required for spectral traits.) | 4000 |
vernaculars (POST)
Vernacular names (GET lists, POST creates).
| Parameter | Required | Description | Example |
|---|---|---|---|
citations | No | List of citations (text + bibreference) for vernaculars. | [{\"citation\":\"Silva 2020\",\"bibreference\":12}] |
individuals | No | List of individual ids/fullnames for vernacular links. | 12|23|45 |
language | Yes | Language id/code/name. For POST vernaculars, registered languages are accepted; absent languages are created from config/languagesISO6393.php only when the informed value matches an ISO639-3 code or configured language name, with is_locale=0. | en or 1 or english or spa |
name | Yes | Translatable trait name. Accepts a plain string or a JSON map of language codes to names. | {"en":"Height","pt-br":"Altura"} |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
parent | No | Parent id/name; for traits this is another trait export_name/id to define hierarchy. | woodDensity |
taxons | No | List of taxon ids/names (vernacular links). | Euterpe edulis|Euterpe precatoria |
type | No | Generic type parameter (trait type code or vernacular type such as use/generic/etimology). | use or 10 |
vouchers (POST)
Voucher specimens (GET lists, POST creates, PUT updates).
| Parameter | Required | Description | Example |
|---|---|---|---|
biocollection | Yes | Biocollection id, name or acronym. | INPA |
biocollection_number | No | Catalogue number/code inside the biocollection. | 12345 |
biocollection_type | No | Nomenclatural type code or name. | Holotype or 2 |
collector | No | Collector(s) id, abbreviation, name or email. Use | or ; to separate multiple people; first is main collector. | J.Silva|M.Costa |
dataset | No | Dataset id or acronym. | 3 or FOREST1 |
date | No | Date (YYYY-MM-DD) or incomplete date (e.g. 1888-05-NA) or array with year/month/day. | 2024-05-20 or {\"year\":1888,\"month\":5} |
individual | Yes | Individual id, uuid or organismID (fullname). | 4521 or 2ff0e884-3d33 |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
number | No | Collector number/code (voucher/individual tag when different from individual). | 1234A |
datasets (POST)
Datasets and published dataset versions (GET lists, POST creates via import job).
| Parameter | Required | Description | Example |
|---|---|---|---|
description | No | Translatable description text. Accepts a plain string or a JSON map of language codes to descriptions. (Required when privacy is 2 or 3.) | {"en":"Tree height at breast height","pt-br":"Altura da árvore à altura do peito"} |
license | No | Public license code for media (CC0, CC-BY, CC-BY-SA, etc.). (Required when privacy is 2 or 3.) | CC-BY-SA |
name | Yes | Short name or nickname for the dataset - make informative, shorter than title. | Morphometrics-Aniba |
privacy | Yes | (Accepted values: 0 (auth), 1 (project), 2 (registered), 3 (public).) | — |
project_id | No | (Required when privacy is 1 (project).) | — |
share_taxon_list | No | Dataset option controlling whether the dataset taxon list can be shared in public phylogeny/taxon-list contexts. (Optional boolean; defaults to true.) | 1 or true |
title | No | (Required when privacy is 2 or 3.) | — |
visibility | No | (Optional for privacy 0 or 1; mandatory true when privacy is 2 or 3.) | — |
identification-histories (POST)
Identification history records (GET lists, POST creates manual history rows).
| Parameter | Required | Description | Example |
|---|---|---|---|
biocollection_id | No | Biocollection id list for voucher filtering. | 1,5 |
biocollection_reference | No | (Requires biocollection_id when provided.) | — |
date | Yes | Date (YYYY-MM-DD) or incomplete date (e.g. 1888-05-NA) or array with year/month/day. | 2024-05-20 or {\"year\":1888,\"month\":5} |
identification_id | No | Identification record id. For POST identification-histories this is optional; when provided, it must belong to individual_id. When omitted, the API derives it from individual_id. (Optional. When provided, it must belong to individual_id; otherwise it is derived from individual_id.) | 123 |
identifier | No | Person(s) responsible for identification; accept id, abbreviation, name or email; separate multiple with | or ;. Required when taxon is informed. Use identifier=collector to use the collector value explicitly provided in the same record, or identifier=keep in updates to preserve the existing identifier. (Provide identifier, identifier_id, or identifiers.) | Costa, A.|Lima, B. or 1|2|3 or collector or keep |
identifier_id | No | Person id or delimited person id list responsible for an identification. (Provide identifier, identifier_id, or identifiers.) | 4 or 4|7 |
identifiers | No | Person reference or delimited person list responsible for an identification. Each item may be a person id, abbreviation, full name, or email. (Provide identifier, identifier_id, or identifiers.) | 4|7 or Costa, A.|Lima, B. |
individual_id | Yes | Individual id list for occurrence queries. | 12,55,90 |
modifier | No | Identification modifier code/name (s.s.=1, s.l.=2, cf.=3, aff.=4, vel aff.=5). | 3 |
notes | No | Free text or JSON notes field. | {\"expedition\":\"2024-01\",\"tag\":\"P1\"} |
replaced_at | No | Timestamp when the identification was replaced. | 2026-06-11 10:30:00 |
source | No | Source label for generated or imported records. | api |
taxon_id | Yes | — |