Add Data

This endpoint allows you to insert new rows into a given database. It also allows you to delete all existing data as you add new data – potentially making updates of the Xtracta App easier since you do not need to track what data has changed since last sync – you can just re-sync completely.

POST Parameters

ParameterRequiredValueDescription
api_key{key}An API key that has access to the resource you want to query for
database_id{integer}The ID of the database which you wish to add data to
data{xml/unicode}The actual data you wish to upload. Structure your XML with each row as a parent tag, then have subtags matching the column_ids for your database with the actual value for that column inside the tag
refresh1, {null}If you want to delete all data already in the database, pass the value of 1 with this POST field. Be very careful, this will delete all information!
Warning

Data Refresh Warning: Using refresh=1 will delete all existing data in the database before adding new data. This action cannot be undone!

Example XML for data:

<row>
  <column id="1">The data for column 1 for this row</column>
  <column id="2">The data for column 2 for this row</column>
</row>
<row>
  <column id="1">The data for column 1 for this row</column>
</row>

Code Examples

The cURL, PHP, Python, Node.js, and C# examples call Xtracta from a trusted server. The React example calls an application-defined backend proxy so the API key is never exposed in browser code.

Warning

Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.

curl --request POST 'https://api-app.xtracta.com/v1/databases/data_add' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'database_id=<DATABASE_ID>' \
  --data-urlencode 'data={xml here}' \
  --data-urlencode 'refresh=1'

Sample Request

POST https://api-app.xtracta.com/v1/databases/data_add HTTP/1.1
api_key=123&database_id=456789&data={xml here}&refresh=1

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<databases_response>
    <status>200</status>
    <message>The request has been successfully processed</message>
    <affected_records>4</affected_records>
    <data>
        <row id="50" />
        <row id="51" />
    </data>
</databases_response>

Schema Definition

Response Elements

ElementDescription
<status>A status code in response to the operation.
<message>Additional information about the operation – human readable.
<affected_records>The number of rows that were affected by the operation.
<data>A container for information about the specific rows that were added.
<data>→<row>The rows (and their Ids) which were added.

Example

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:complexType name="RowType"><xs:sequence/><xs:attribute name="id" type="xs:positiveInteger" use="required"/></xs:complexType>
  <xs:complexType name="DataType"><xs:sequence><xs:element name="row" type="RowType" maxOccurs="unbounded"/></xs:sequence></xs:complexType>
  <xs:element name="databases_response"><xs:complexType><xs:sequence>
    <xs:element name="status" type="xs:positiveInteger"/><xs:element name="message" type="xs:string"/>
    <xs:element name="affected_records" type="xs:nonNegativeInteger" minOccurs="0"/><xs:element name="data" type="DataType" minOccurs="0"/>
  </xs:sequence></xs:complexType></xs:element>
</xs:schema>

Error Responses

For JSON and XML responses generated by this endpoint, the response is wrapped in databases_response and includes the HTTP status code and a message.

StatusMessageDescription
400database_id is required / database_id must be natural numberSupply the positive integer database ID.
400refresh must be '0' or '1'Use 1 to clear existing data first or 0 to append.
400data is required / Invalid XML format provided in data parameterSupply well-formed XML in data.
400Invalid XML structure is detectedInclude at least one <row><column>...</column></row> structure.
400column id=... / column id=... does not belong to specified databaseUse numeric column IDs from the selected database.
400Neither column id nor column name is specified / column name=... does not belong to specified databaseIdentify every submitted column by a valid ID or name.
202No data has been addedThe request was valid, but it contained no non-empty row data to add.
500Internal server error occurred. Please try again later or contact support@xtracta.comRetry and contact support with the request parameters and timestamp if it persists.
Information Circle

Authentication, permission, IP-access-control, and rate-limit failures can be returned before this endpoint processes the request. Confirm the API key and caller access first.