Conformance Testing

Stage 3: User Management

User management is critical for B2B partners managing evaluation traders. This stage validates your integration’s ability to create, manage, and terminate users within the evaluation system.

Overview

The user management stage ensures your application can:

  • Create evaluation users with proper configuration
  • Manage user entitlements and permissions
  • Terminate users and clean up associated resources
  • Handle user lifecycle events and state changes

Required Tests

1. User Creation

Endpoint: POST /user/createevaluationusers

Response
1{
2  "results": [
3    {
4      "errorText": "string",
5      "userId": 1
6    }
7  ],
8  "errorText": "string"
9}

Purpose: Create new evaluation users for the trading platform.

Test Steps:

  1. Create a single evaluation user with valid parameters
  2. Optionally, create multiple users in batch (up to 100)
  3. Store the user ID in your system for future reference

Example Request:

1// Single user creation
2const requestBody = {
3    users: [{
4        name: "testuser1",
5        email: "testuser1@example.com",
6        password: "SecurePassword123!",
7        firstName: "Test",
8        lastName: "User",
9    }]
10};
11
12const response = await fetch('https://live.tradovateapi.com/v1/user/createevaluationusers', {
13    method: 'POST',
14    headers: {
15        'Authorization': `Bearer ${accessToken}`,
16        'Content-Type': 'application/json',
17        'Accept': 'application/json'
18    },
19    body: JSON.stringify(requestBody)
20});
21
22const data = await response.json();

Batch User Creation:

1// Batch user creation (up to 100 users)
2const requestBody = {
3    users: Array.from({ length: 10 }, (_, i) => ({
4        name: `testuser${i + 1}`,
5        email: `testuser${i + 1}@example.com`,
6        password: `SecurePassword${i + 1}!`,
7        firstName: "Test",
8        lastName: `User${i + 1}`,
9    }))
10};
11
12const response = await fetch('https://live.tradovateapi.com/v1/user/createevaluationusers', {
13    method: 'POST',
14    headers: {
15        'Authorization': `Bearer ${accessToken}`,
16        'Content-Type': 'application/json',
17        'Accept': 'application/json'
18    },
19    body: JSON.stringify(requestBody)
20});

Expected Response:

1{
2    "results": [
3        {
4            "id": 12345,
5            "name": "testuser1",
6            "email": "testuser1@example.com",
7            "firstName": "Test",
8            "lastName": "User",
9            "status": "Active",
10            "createdAt": "2024-01-01T12:00:00.000Z"
11        }
12    ],
13    "errorText": ""
14}

Validation Criteria:

  • ✅ Users are created successfully with valid data
  • ✅ Batch creation works for multiple users
  • ✅ User data is stored correctly
  • ✅ Duplicate usernames/emails are rejected
  • ✅ Invalid data returns appropriate errors

2. Contact Information Management (Optional)

Endpoint: POST /contactinfo/updatecontactinfo

Purpose: Update user contact information after user creation, this is optional but recommended.

Test Steps:

  1. Update user contact information with valid data
  2. Verify contact information is updated correctly
  3. Test error handling for invalid contact data
  4. Verify contact information validation rules

Example Request:

1const contactUpdate = {
2    userId: 12345,
3    phone: "+1234567890",
4    firstName: "John",
5    lastName: "Doe",
6    streetAddress1: "123 Main St",
7    city: "New York",
8    state: "NY", // only required when country is "US"
9    postCode: "12345",
10    country: "US",
11};
12
13const response = await fetch('https://live.tradovateapi.com/v1/contactinfo/updatecontactinfo', {
14    method: 'POST',
15    headers: {
16        'Authorization': `Bearer ${accessToken}`,
17        'Content-Type': 'application/json',
18        'Accept': 'application/json'
19    },
20    body: JSON.stringify(contactUpdate)
21});
22
23const data = await response.json();

Expected Response:

1{
2    "success": true,
3    "message": "Contact information updated successfully",
4    "userId": 12345,
5    "updatedAt": "2024-01-01T12:00:00.000Z"
6}

Validation Criteria:

  • ✅ Contact information is updated successfully
  • ✅ Phone number validation works correctly
  • ✅ Address validation works correctly
  • ✅ Invalid data returns appropriate errors
  • ✅ User ID validation works correctly

3. Entitlement Management

Endpoints:

  • POST /userPlugin/addentitlementsubscription
  • POST /user/canceleverything

Purpose: Manage user Sim+ entitlement.

Test Steps:

  1. Wait for user to be verified (they must sign the Market Data Agreement)
  2. Add Sim+ entitlement subscriptions to verified users
  3. Cancel all subscriptions and permissions for users at the end of their lifecycle

Add Entitlement Subscription:

1async function addEntitlementWithAgreementCheck(userId, accountId) {
2    // Step 1: Check for agreement signatures using adminAlertSignal/deps, use masterid=70 in staging
3    const alertResponse = await fetch(`https://live.tradovateapi.com/v1/adminAlertSignal/deps?masterid=68`, {
4        method: 'GET',
5        headers: {
6            'Authorization': `Bearer ${accessToken}`,
7            'Accept': 'application/json'
8        }
9    });
10    
11    const alerts = await alertResponse.json();
12    
13    // Step 2: Find alerts for the specific user that don't have 'complete' field
14    const pendingAgreements = alerts.filter(alert => !alert.complete);
15    
16    if (pendingAgreements.length === 0) {
17        console.log('No pending agreements found for user:', userId);
18        return { success: false, message: 'No pending agreements found' };
19    }
20    
21    // Step 3: Add the entitlement subscription
22    const addEntitlement = {
23        entitlementId: 12345, // Required: ID of the entitlement to add
24        userId: userId,
25        accountId: accountId, // This should be the ID of your Live _DATA account.
26    };
27
28    const entitlementResponse = await fetch('https://live.tradovateapi.com/v1/userPlugin/addentitlementsubscription', {
29        method: 'POST',
30        headers: {
31            'Authorization': `Bearer ${accessToken}`,
32            'Content-Type': 'application/json',
33            'Accept': 'application/json'
34        },
35        body: JSON.stringify(addEntitlement)
36    });
37
38    const entitlementData = await entitlementResponse.json();
39    
40    // Step 4: Complete the alert signal after successful entitlement addition
41    if (entitlementData.errorCode === 'Success') {
42        for (const alert of pendingAgreements) {
43            await fetch('https://live.tradovateapi.com/v1/adminAlertSignal/completealertsignal', {
44                method: 'POST',
45                headers: {
46                    'Authorization': `Bearer ${accessToken}`,
47                    'Content-Type': 'application/json',
48                    'Accept': 'application/json'
49                },
50                body: JSON.stringify({
51                    alertId: alert.id,
52                    userId: userId
53                })
54            });
55        }
56    }
57    
58    return entitlementData;
59}
60
61// Usage example
62const result = await addEntitlementWithAgreementCheck(67890, 11111);
63console.log('Entitlement addition result:', result);

Cancel Everything (All Subscriptions and Permissions):

1const cancelEverything = {
2    userIds: [12345, 67890], // Required: Array of user IDs
3    tradovateSubscriptions: true, // Optional: Cancel Tradovate subscriptions
4    tradingPermissions: true, // Optional: Revoke trading permissions
5    userPlugins: true, // Optional: Cancel user plugin subscriptions
6    marketDataSubscriptions: true // Optional: Cancel market data subscriptions
7};
8
9const response = await fetch('https://live.tradovateapi.com/v1/user/canceleverything', {
10    method: 'POST',
11    headers: {
12        'Authorization': `Bearer ${accessToken}`,
13        'Content-Type': 'application/json',
14        'Accept': 'application/json'
15    },
16    body: JSON.stringify(cancelEverything)
17});
18
19const data = await response.json();

Expected Response for Add Entitlement:

1{
2    "errorText": "",
3    "errorCode": "Success",
4    "entitlementSubscription": {
5        "id": 99999,
6        "userId": 67890,
7        "accountId": 11111,
8        "entitlementId": 12345,
9        "status": "Active",
10        "createdAt": "2024-01-01T12:00:00.000Z"
11    }
12}

Expected Response for Cancel Everything:

1{
2    "success": true,
3    "cancelledUsers": [12345, 67890],
4    "tradovateSubscriptionsCancelled": 2,
5    "tradingPermissionsRevoked": 2,
6    "userPluginsCancelled": 1,
7    "marketDataSubscriptionsCancelled": 2
8}

Validation Criteria:

  • ✅ Agreement signatures are checked before adding entitlements
  • ✅ Entitlements are only added for users with pending agreements (no ‘complete’ field)
  • ✅ Alert signals are completed after successful entitlement addition
  • ✅ Entitlement subscriptions are added successfully
  • ✅ Required entitlementId parameter is validated
  • ✅ Cancel everything works for multiple users
  • ✅ All subscription types are cancelled when requested
  • ✅ Invalid entitlement operations are rejected
  • ✅ Entitlement changes are reflected immediately
  • ✅ Billing and payment handling works correctly

User Lifecycle Management

Required Fields for User Creation

  • name: Unique username (3-64 characters)
  • email: Valid email address (max 64 characters)
  • password: Secure password (8-64 characters)
  • firstName: First name (max 64 characters)
  • lastName: Last name (2-64 characters)

Optional Fields

  • tradovateSubscriptionPlanId: Organization-specific subscription plan ID (integer > 0)
  • entitlementIds: Array of entitlement IDs to pre-assign (array of integers)
  • NOTE: Do not pass the Sim+ entitlement here, users are not valid until they sign the Market Data Agreement

Testing Checklist

  • Single user creation works correctly
  • Batch user creation works for multiple users
  • User data validation works properly
  • Duplicate user prevention works
  • Subscription management functions correctly
  • User termination works properly
  • Resource cleanup is complete
  • Error handling is robust
  • Performance requirements are met
  • Security requirements are satisfied

Next Steps

After completing Stage 3 user management tests, proceed to Stage 4: Account Management.