## Add Database

This endpoint allows you to create a new database in your Xtracta account.

## POST Parameters

{% apiTable %}
| Parameter | Required | Value | Description |
|-----------|----------|-------|-------------|
| `api_key` | {% requiredIcon type="required" /%} | `{key}` | An API key that has access to the resource you want to query for |
| `database_name` | {% requiredIcon type="required" /%} | `{unicode}` | The name for the new database. Please note there are certain naming convention requirements |
| `group_id` | {% requiredIcon type="optional" /%} | `{integer}` | The ID of the group where you want to create the database |
{% /apiTable %}

## 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.

{% callout type="warning" %}
Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.
{% /callout %}

{% tabbedCodeExamples %}
```bash
curl --request POST 'https://api-app.xtracta.com/v1/databases/add' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'group_id=<GROUP_ID>' \
  --data-urlencode 'database_name=MyNewDatabase'
```

```php
<?php
$endpoint = 'https://api-app.xtracta.com/v1/databases/add';
$payload = [
    'api_key' => getenv('XTRACTA_API_KEY'),
    'group_id' => '<GROUP_ID>',
    'database_name' => 'MyNewDatabase',
];

$curl = curl_init($endpoint);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($payload),
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/x-www-form-urlencoded',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException('Xtracta returned HTTP ' . $status . ': ' . $body);
}

$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
```

```python
import os
import requests

response = requests.post(
    "https://api-app.xtracta.com/v1/databases/add",
    headers={"Accept": "application/json"},
    data={
        "api_key": os.environ["XTRACTA_API_KEY"],
        "group_id": "<GROUP_ID>",
        "database_name": "MyNewDatabase",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
```

```javascript
const body = new URLSearchParams({
  "api_key": process.env.XTRACTA_API_KEY,
  "group_id": "<GROUP_ID>",
  "database_name": "MyNewDatabase",
});

const response = await fetch('https://api-app.xtracta.com/v1/databases/add', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body,
});

if (!response.ok) {
  throw new Error('Xtracta returned HTTP ' + response.status + ': ' + await response.text());
}

const data = await response.json();
```

```csharp
using System.Net.Http.Headers;

using var client = new HttpClient {
    Timeout = TimeSpan.FromSeconds(30)
};
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json")
);

using var content = new FormUrlEncodedContent(new Dictionary<string, string> {
    ["api_key"] = Environment.GetEnvironmentVariable("XTRACTA_API_KEY")!,
    ["group_id"] = "<GROUP_ID>",
    ["database_name"] = "MyNewDatabase",
});

using var response = await client.PostAsync("https://api-app.xtracta.com/v1/databases/add", content);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();
```

```jsx
async function callXtracta() {
  const response = await fetch('/api/xtracta/databases/add', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      "group_id": "<GROUP_ID>",
      "database_name": "MyNewDatabase",
    }),
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}
```
{% /tabbedCodeExamples %}

## Sample Request

```
POST https://api-app.xtracta.com/v1/databases/add HTTP/1.1
api_key=123&group_id=456&database_name=MyNewDatabase
```

## Sample Response

{% tabbedResponse  title="" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<databases_response>
    <status>200</status>
    <message>The request has been successfully processed</message>
    <database_id>12345</database_id>
</databases_response>
```

{% /tabbedResponse %}

## Schema Definition


{% tabbedSchema title="" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

  <xs:simpleType name="ConfidenceType">
    <xs:union>
      <xs:simpleType>
        <xs:restriction base="xs:integer">
          <xs:minInclusive value="0"/>
          <xs:maxInclusive value="100"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value=""/>
        </xs:restriction>
      </xs:simpleType>
    </xs:union>
  </xs:simpleType>

  <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="database_id" type="xs:integer" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
```

{% /tabbedSchema %}
## 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`.

{% apiTable %}
| Status | Message | Description |
|---|---|---|
| `400` | database_name is required | Supply a database name. |
| `400` | database_name cannot exceed 100 characters | Shorten the database name to 100 characters or fewer. |
| `500` | Internal server error occurred. Please try again later or contact support@xtracta.com | Retry and contact support with the request parameters and timestamp if it persists. |
{% /apiTable %}

{% callout type="note" %}
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.
{% /callout %}


Add Database

Logging In

Overview

Home Page

Supported Languages

Get started

My Account

Workflow Overview

Uploading Documents

ELS Overview

Splitting Pages

Engine Learning Screen

New ELS Overview

Edit Document and Pages

Change Field Highlight Color

Learn & Extract

Learn & Extract (Previously Auto Line Extraction )

New Engine Learning Screen (New ELS)

User Manual

Get Document(s)

Update Document

Upload Document

Open Document UI

Open Document Upload UI

Open Reassign Pages

Documents

Create Batch

Update Batch

Get Batches

Get Batch Workflow

Batches

Get Tracking

Update Tracking Status

Tracking

Open Dashboard

Open Tracking Dashboard

Dashboard

Get Databases

Update Database

Delete Database

Get Columns

Update Column

Add Column

Delete Column

Get Data

Add Data

Update Data

Delete Data

Database

Provisioning

Get Workflow

Update Workflow

Add Workflow from Template

Clone Workflow

Workflow

Delete Group

Add Group

List Group

Group

Get User

Add User

Update User

Delete User

Get Login Token

Authorize

User

Open Billing UI

Get Plans

Get Usage

Renew/Upgrade/Downgrade Plan

Get Billing History

Order Pack

Billing

Announcements

API Manual

Billing Settings

General Settings

Groups

OCR Override

Time Alerts

Confidence

Extraction & Classification

Clone a workflow

Reassignment / Output Non-API

Conditions

Permissions

Auto Deletion

AI Data Transformation

Fields

Transformation Order

Advanced Transformation

Workflow Details

Strip & Replace Rules

Creating a workflow

Input & Document Flow

Extraction Helper

Advanced Validation

Workflows

Users

Admin Manual

Databases

IP Access Control

Client Applications

Client Push Application

Applications

Alerts

Single Sign On (SSO)

Peppol Participants

General FAQs

Why is a document locked?

Which URL`s are needed for Xtracta to go through a firewall?

What type of documents are accepted by Xtracta?

What is a workflow?

What are the different statuses for a document?

What are the status for a document?

What does training a document mean?

What are the options when a document is selected?

What is Regex?

How does a document get a class and a designn?

How does a document get a class and a design?

How many pages and Line Items can Xtracta process?

Frequently Asked Questions

Parameter	Required	Value	Description
`api_key`	✅	`{key}`	An API key that has access to the resource you want to query for
`database_name`	✅	`{unicode}`	The name for the new database. Please note there are certain naming convention requirements
`group_id`		`{integer}`	The ID of the group where you want to create the database

Status	Message	Description
`400`	database_name is required	Supply a database name.
`400`	database_name cannot exceed 100 characters	Shorten the database name to 100 characters or fewer.
`500`	Internal server error occurred. Please try again later or contact support@xtracta.com	Retry and contact support with the request parameters and timestamp if it persists.

Add Database

POST Parameters

Code Examples

Sample Request

Sample Response

Schema Definition

Error Responses

Was this page helpful?