Provisioning – API

The provision endpoint allows you to create a new set of objects (typically everything needed for a new client account). This is based on the provisioning profile you call, which may include actions such as:

Creating a new group
Assigning a billing plan to the new group
Creating a workflow
Creating database(s)
Generating an API key
Dynamically building links between workflows and databases

What is Provisioning? This endpoint is designed for automated client onboarding and creates complete account setups in a single API call. It's commonly used by integrators and resellers to quickly set up new customer accounts with pre-configured workflows and databases.

Security Feature: Unlike all other API calls, this endpoint does NOT require a standard API key. It can use a provisioning key, recommended especially when calling from distributed software outside your control. This protects your API key from being compromised.

Click here to go to API Previewer page.

POST Parameters

Parameter	Required	Value	Description
`api_key`	⚠️	`{key}`	An API key that has access to the resource you want to query for
`provisioning_key`	⚠️	`{key}`	A provisioning key that has access to the profile ID you are calling
`profile_id`	✅	`{integer}`	The ID of a provisioning profile to use
`identifier`	✅	`{unicode}`	Unique identifier of the user requesting provisioning (usually customer name)
`group_name`		`{unicode}`	Name for the new group. Defaults to the identifier if left blank
`group_id`		`{integer}`	Optional ID of the parent group. Defaults to top-level
`input_account`		`{string}`	Prefix for email and FTP input methods

Authentication Requirements:

Either api_key OR provisioning_key must be provided (⚠️ indicates exactly one is required)
Do not provide both keys in the same request
Provisioning keys are recommended for distributed software environments

Response Information

Element	Description
`<status>`	A status code in response to the operation
`<message>`	Additional information about the operation – human readable
`<group>`	Container for group information
`<group_id>`	The ID of the newly created group
`<group_name>`	The name of the newly created group
`<billing_plan>`	Container for billing plan information
`<billing_plan_id>`	The ID of the assigned billing plan
`<billing_plan_name>`	The name of the assigned billing plan
`<billing_plan_details>`	Details about the billing plan including document limits
`<workflow>`	Container for workflow information
`<workflow_id>`	The ID of the created workflow
`<workflow_name>`	The name of the created workflow
`<workflow_email>`	The email address for document submission to this workflow
`<workflow_file_transfer>`	The SFTP/FTP connection details for file uploads
`<database>`	Container for database information (can appear multiple times)
`<database_id>`	The ID of a created database
`<database_name>`	The name of a created database
`<column>`	Container for column information within each database
`<column_id>`	The ID of a database column
`<column_name>`	The name of a database column
`<api_key>`	The generated API key for accessing the new group's resources

Sample Request

POST https://api-app.xtracta.com/v1/provisioning/provision HTTP/1.1
Content-Type: application/x-www-form-urlencoded
provisioning_key=123&profile_id=456789&identifier=Acme%20Industries&group_name=Acme%20Industries

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<provisioning_response>
    <status>200</status>
    <message>The request has been successfully processed</message>
    <group>
        <group_id>124</group_id>
        <group_name>Acme Industries</group_name>
    </group>
    <billing_plan>
        <billing_plan_id>123</billing_plan_id>
        <billing_plan_name>Free</billing_plan_name>
        <billing_plan_details>25 documents free per month.</billing_plan_details>
    </billing_plan>
    <workflow>
        <workflow_id>123</workflow_id>
        <workflow_name>Accounts Payable</workflow_name>
        <workflow_email>tmlo152@sample.xtracta.com</workflow_email>
        <workflow_file_transfer>tmlo152:%2A%28S%40%28%5EDS%26%2A@transfer-sample.xtracta.com</workflow_file_transfer>
    </workflow>
    <database>
        <database_id>1235</database_id>
        <database_name>Suppliers</database_name>
        <column>
            <column_id>51251</column_id>
            <column_name>Supplier Code</column_name>
        </column>
        <column>
            <column_id>62323</column_id>
            <column_name>Supplier Name</column_name>
        </column>
        <column>
            <column_id>635234</column_id>
            <column_name>Address</column_name>
        </column>
    </database>
    <database>
        <database_id>1234</database_id>
        <database_name>Open Purchase Orders</database_name>
        <column>
            <column_id>7634221</column_id>
            <column_name>PO Number</column_name>
        </column>
        <column>
            <column_id>2376812</column_id>
            <column_name>PO Amount</column_name>
        </column>
        <column>
            <column_id>2376812</column_id>
            <column_name>Supplier Code</column_name>
        </column>
    </database>
    <api_key>8901248791478912</api_key>
</provisioning_response>

Schema Definition

<?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:complexType name="WorkflowType">
    <xs:sequence>
      <xs:element name="workflow_id" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="workflow_name" type="xs:string"/>
      <xs:element name="workflow_email" type="xs:string"/>
      <xs:element name="workflow_file_transfer" type="xs:string"/>
      <xs:element name="source_workflow_id" type="xs:nonNegativeInteger"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="ProvisioningresponseType">
    <xs:sequence>
      <xs:element name="status" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="message" type="xs:string"/>
      <xs:element name="group" type="GroupType"/>
      <xs:element name="billing_plan" type="BillingplanType"/>
      <xs:element name="workflow" type="WorkflowType"/>
      <xs:element name="database" type="xs:string"/>
      <xs:element name="api_key" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="GroupType">
    <xs:sequence>
      <xs:element name="group_id" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="group_name" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="BillingplanType">
    <xs:sequence>
      <xs:element name="billing_plan_id" type="xs:nonNegativeInteger"/>
      <xs:element name="billing_plan_name" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="provisioning_response">
    <xs:complexType>
      <xs:sequence>
      <xs:element name="status" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="message" type="xs:string"/>
      <xs:element name="group" type="GroupType"/>
      <xs:element name="billing_plan" type="BillingplanType"/>
      <xs:element name="workflow" type="WorkflowType"/>
      <xs:element name="database" type="xs:string"/>
      <xs:element name="api_key" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>

Provisioning – API

Sample Response

Schema Definition

Was this page helpful?