Provisioning

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
Information Circle

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.

Information Circle

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

ParameterRequiredValueDescription
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
Information Circle

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

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_PROVISIONING_KEY as a server-side environment variable. Never embed it in browser-delivered code.

curl --request POST 'https://api-app.xtracta.com/v1/provisioning/provision' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'provisioning_key=<PROVISIONING_KEY>' \
  --data-urlencode 'profile_id=<PROFILE_ID>' \
  --data-urlencode 'identifier=Acme Industries' \
  --data-urlencode 'group_name=Acme Industries'

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>
    <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>
        <source_workflow_id>456</source_workflow_id>
    </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

Response Elements

ElementDescription
<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
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:complexType name="GroupType"><xs:sequence><xs:element name="group_id" type="xs:positiveInteger" minOccurs="0"/><xs:element name="group_name" type="xs:string" minOccurs="0"/></xs:sequence></xs:complexType>
  <xs:complexType name="BillingPlanType"><xs:sequence><xs:element name="billing_plan_id" type="xs:nonNegativeInteger" minOccurs="0"/><xs:element name="billing_plan_name" type="xs:string" minOccurs="0"/></xs:sequence></xs:complexType>
  <xs:complexType name="WorkflowType"><xs:sequence><xs:element name="workflow_id" type="xs:positiveInteger" minOccurs="0"/><xs:element name="workflow_name" type="xs:string" minOccurs="0"/><xs:element name="workflow_email" type="xs:string" minOccurs="0"/><xs:element name="workflow_file_transfer" type="xs:string" minOccurs="0"/><xs:element name="source_workflow_id" type="xs:string" minOccurs="0"/></xs:sequence></xs:complexType>
  <xs:complexType name="ColumnType"><xs:sequence><xs:element name="column_id" type="xs:positiveInteger"/><xs:element name="column_name" type="xs:string"/></xs:sequence></xs:complexType>
  <xs:complexType name="DatabaseType"><xs:sequence><xs:element name="database_id" type="xs:positiveInteger" minOccurs="0"/><xs:element name="database_name" type="xs:string" minOccurs="0"/><xs:element name="column" type="ColumnType" minOccurs="0" maxOccurs="unbounded"/></xs:sequence></xs:complexType>
  <xs:element name="provisioning_response"><xs:complexType><xs:sequence>
    <xs:element name="status" type="xs:positiveInteger"/><xs:element name="message" type="xs:string"/>
    <xs:element name="task_id" type="xs:positiveInteger" minOccurs="0"/><xs:element name="group" type="GroupType" minOccurs="0"/>
    <xs:element name="billing_plan" type="BillingPlanType" minOccurs="0"/><xs:element name="workflow" type="WorkflowType" minOccurs="0" maxOccurs="unbounded"/>
    <xs:element name="database" type="DatabaseType" minOccurs="0" maxOccurs="unbounded"/><xs:element name="api_key" type="xs:string" 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 provisioning_response and includes the HTTP status code and a message.

StatusMessageDescription
400profile_id is required / profile_id must be natural numberSupply the positive integer provisioning profile ID.
400identifier is required / group_name is requiredSupply the identifier required by the selected provisioning profile.
400<parameter> cannot exceed 256 charactersShorten identifier or group_name.
400input_account cannot be below 1 charactersWhen supplied, input_account cannot be empty.
400Billing plan in this provisioning profile is not available for specified group(...)Select a profile whose billing plan is available to the API-key group.
202The request is being processedProvisioning has started but is not complete. Retry later with the same profile and identifier.
201The request has been already processedThe same provisioning task already completed; the existing result is returned.
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.