Add Group

Add a new group to your Xtracta account.

POST Parameters

ParameterRequiredValueDescription
api_key{key}An API key that has access to the resource you want to query for
group_id{integer}ID of the parent group (if creating a subgroup). If omitted, creates a top-level group
group_name{unicode}Name of the group
inactivity_limit{integer}Inactive log out time (in minutes)
password_expiry{integer}Number of days before users need to reset their password
block_password_reuse{integer}Number of days to prevent reuse of old passwords
Information Circle

Group Hierarchy: Use group_id to specify a parent group when creating subgroups. This creates a hierarchical structure that can help organize different departments or teams.

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/group/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 'group_name=demo group'

Sample Request

POST https://api-app.xtracta.com/v1/group/add HTTP/1.1
api_key=123&group_id=12345&group_name=demo group

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<group_response>
    <status>200</status>
    <message>Successfully created new group</message>
    <group>
        <group_id>12345</group_id>
        <parent_id>12345</parent_id>
        <name>demo group</name>
        <is_data_extraction_enabled>1</is_data_extraction_enabled>
        <password_expiry>1461</password_expiry>
        <block_password_reuse>0</block_password_reuse>
        <inactivity_limit>10</inactivity_limit>
    </group>
</group_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>→<group_id>The unique ID of the created group
<group>→<parent_id>The ID of the parent group (if applicable)
<group>→<name>The name of the group
<group>→<is_data_extraction_enabled>Whether data extraction is enabled for this group (1 = enabled, 0 = disabled)
<group>→<password_expiry>Number of days before password expiry
<group>→<block_password_reuse>Number of days to block password reuse
<group>→<inactivity_limit>Inactive logout time in minutes
<?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="GroupresponseType">
    <xs:sequence>
      <xs:element name="status" type="xs:positiveInteger"/>
      <xs:element name="message" type="xs:string"/>
      <xs:element name="group" type="GroupType"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="GroupType">
    <xs:sequence>
      <xs:element name="group_id" type="xs:positiveInteger"/>
      <xs:element name="parent_id" type="xs:nonNegativeInteger"/>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="is_data_extraction_enabled" type="xs:nonNegativeInteger"/>
      <xs:element name="password_expiry" type="xs:nonNegativeInteger"/>
      <xs:element name="block_password_reuse" type="xs:nonNegativeInteger"/>
      <xs:element name="inactivity_limit" type="xs:nonNegativeInteger"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="group_response">
    <xs:complexType>
      <xs:sequence>
      <xs:element name="status" type="xs:positiveInteger"/>
      <xs:element name="message" type="xs:string"/>
      <xs:element name="group" type="GroupType" minOccurs="0"/>
        <xs:element name="error" 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 group_response and includes the HTTP status code and a message.

StatusMessageDescription
400group_id must be natural numberUse a positive integer parent group ID.
400group_name is requiredSupply the new group name.
400<parameter> must be natural numberInactivity, password-expiry, and password-reuse limits must use positive integers.
400Invalid requestGroup creation failed; the response error value contains the underlying reason.
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.