Add User

This endpoint allows you to add users for either a group or specific workflows.

Information Circle

User Creation: New users can be assigned directly to groups or workflows. If token_expire is specified, a login token and QR code will be generated for the user.

POST Parameters

ParameterRequiredValueDescription
api_key{key}An API key that has access to the resource you want to query for
name{string}Full name of the user
email_address{string}Email address of the user
password{string}User's password (if not provided, user will need to set password on first login)
group_id{integer}The ID of a specific group to assign user to
workflow_ids{integer}Comma-separated list of workflow IDs to assign user to
token_expire{integer}Time in seconds for login token expiry (returns token and QR code). Maximum: 86400

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/user/add' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'name=John' \
  --data-urlencode 'email_address=<EMAIL_ADDRESS>' \
  --data-urlencode 'password=<PASSWORD>' \
  --data-urlencode 'group_id=<GROUP_ID>'

Sample Request

POST https://api-app.xtracta.com/v1/user/add HTTP/1.1
api_key=123&name=John&email_address=john@xtracta.com&password=12345678&group_id=12345

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<user_response>
	<status>200</status>
	<message>The request has been successfully processed</message>
	<user>
		<user_id>4092</user_id>
		<name>John</name>
		<email_address>John@example.com</email_address>
		<primary_group_id>130</primary_group_id>
		<assigned_workflows/>
		<password>John1234</password>
	</user>
</user_response>

Schema Definition

Response Elements

ElementDescription
<status>A status code in response to the operation.
<message>Additional information about the operation – human readable.
<user_id>The users id.
<name>Name of the user.
<email_address>Email address of the user
<primary_group_id>The users assigned primary group.
<assigned_workflows>A list of workflows the user has been assigned to.
<<password>>The user password

Example

<?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="UserresponseType">
    <xs:sequence>
      <xs:element name="status" type="xs:positiveInteger"/>
      <xs:element name="message" type="xs:string"/>
      <xs:element name="user" type="UserType"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="UserType">
    <xs:sequence>
      <xs:element name="user_id" type="xs:nonNegativeInteger"/>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="email_address" type="xs:string"/>
      <xs:element name="primary_group_id" type="xs:nonNegativeInteger"/>
      <xs:element name="assigned_workflows" type="xs:string" nillable="true"/>
      <xs:element name="password" type="xs:string" minOccurs="0"/>
      <xs:element name="token" type="xs:string" minOccurs="0"/>
      <xs:element name="qrcode" type="xs:anyURI" minOccurs="0"/>
      <xs:element name="expire" type="xs:nonNegativeInteger" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="user_response">
    <xs:complexType>
      <xs:sequence>
      <xs:element name="status" type="xs:positiveInteger"/>
      <xs:element name="message" type="xs:string"/>
      <xs:element name="user" type="UserType" 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 user_response and includes the HTTP status code and a message.

StatusMessageDescription
400email_address is required / email_address must be email address formatSupply a valid email address.
400<email availability message>The email address is already in use or otherwise unavailable.
400name is required / name cannot exceed 255 charactersSupply a user name of 255 characters or fewer.
400<password validation message>Supply a password that meets the current password policy, or omit it to generate one.
400group_id must be natural numberUse a positive integer group ID.
400workflow_ids must be comma separeted numbersSupply workflow IDs as comma-separated integers.
400token_expire must be natural number / token_expire must be less than 86400Supply a positive token lifetime below 86,400 seconds.
500Failed to create userUser creation did not complete. Retry, then contact support if it persists.
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.