# Traders Room — Sign Up API

The **Sign Up API** allows external systems to **register new clients** in the platform.

It supports:

- Creating a new user
- Passing marketing / affiliate data
- Passing business / routing configuration
- Optional email notification
- Optional instant login via autologin link

---

## 🎯 Use Cases

- Partner platforms
- Affiliate systems
- Landing pages / funnels
- External onboarding flows

---

## 🌐 Endpoint

```
POST /tradersroom/api/auth/signup

```

---

## 🔐 Authentication

All external requests **must include an API key**.

### Header

```
x-api-key: <your-api-key>

```

---

## ⚙️ Request Format

### Headers

<table id="bkmrk-header-required-valu"><thead><tr><th>Header</th><th>Required</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td>✅</td><td>application/json</td></tr><tr><td>x-api-key</td><td>✅</td><td>Provided by platform</td></tr><tr><td>Origin</td><td>❌</td><td>Your domain</td></tr></tbody></table>

---

## 📥 Request Body

### Required Fields

```json
{
  "email": "user@example.com",
  "phone": "+1234567890",
  "firstName": "Jane"
}

```

---

## 📊 Full Field Reference

### 🧑 Basic Information

<table id="bkmrk-field-type-required-"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>email</td><td>string</td><td>✅</td><td>User email</td></tr><tr><td>phone</td><td>string</td><td>✅</td><td>Phone number</td></tr><tr><td>firstName</td><td>string</td><td>✅</td><td>First name</td></tr><tr><td>middleName</td><td>string</td><td>❌</td><td>Middle name</td></tr><tr><td>lastName</td><td>string</td><td>❌</td><td>Last name</td></tr><tr><td>gender</td><td>string</td><td>❌</td><td>Gender</td></tr><tr><td>dateOfBirth</td><td>string</td><td>❌</td><td>Date of birth (ISO format)</td></tr><tr><td>nationality</td><td>string</td><td>❌</td><td>Nationality</td></tr><tr><td>passport</td><td>string</td><td>❌</td><td>Passport</td></tr></tbody></table>

---

### 📞 Contact Information

<table id="bkmrk-field-type-required--1"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>additionalPhone</td><td>string</td><td>❌</td><td>Secondary phone</td></tr></tbody></table>

---

### 📢 Affiliate &amp; Marketing

<table id="bkmrk-field-type-required--2"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>affiliateID</td><td>string</td><td>❌</td><td>Affiliate identifier</td></tr><tr><td>subID</td><td>string</td><td>❌</td><td>Affiliate sub-id</td></tr><tr><td>campaignId</td><td>string</td><td>❌</td><td>Campaign identifier</td></tr><tr><td>sourceId</td><td>string</td><td>❌</td><td>Traffic source</td></tr><tr><td>meta</td><td>string</td><td>❌</td><td>Additional metadata</td></tr><tr><td>externalId</td><td>string</td><td>❌</td><td>External system user ID</td></tr></tbody></table>

---

### 🏢 Business / Routing Configuration

<table id="bkmrk-field-type-required--3"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>project</td><td>string</td><td>❌</td><td>Project identifier</td></tr><tr><td>desk</td><td>string</td><td>❌</td><td>Desk identifier</td></tr><tr><td>manager</td><td>string</td><td>❌</td><td>Manager (id / email / name)</td></tr><tr><td>status</td><td>string</td><td>❌</td><td>Client status</td></tr><tr><td>state</td><td>string</td><td>❌</td><td>Client state (`active`, `live`, etc.)</td></tr><tr><td>type</td><td>string</td><td>❌</td><td>Client type</td></tr><tr><td>companyFeeGroup</td><td>string</td><td>❌</td><td>Fee group</td></tr><tr><td>processed</td><td>boolean</td><td>❌</td><td>Used in custom flows</td></tr></tbody></table>

---

### 🛡️ Verification &amp; Permissions

<table id="bkmrk-field-type-required--4"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>verificationLevel</td><td>string</td><td>❌</td><td>Verification level</td></tr><tr><td>verificationStatus</td><td>string</td><td>❌</td><td>Verification status</td></tr><tr><td>allowToCreateAsset</td><td>boolean</td><td>❌</td><td>Allow asset creation</td></tr><tr><td>agreements</td><td>array</td><td>❌</td><td>Signed agreements</td></tr></tbody></table>

---

### ⚙️ Traders Room Options

<table id="bkmrk-field-type-required--5"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>sendEmail</td><td>boolean</td><td>❌</td><td>Send registration email</td></tr></tbody></table>

---

## 📦 Nested Objects

### billing

```json
{
  "billing": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "postcode": "10001",
    "address": "Wall Street 1"
  }
}

```

<table id="bkmrk-field-type-country-s"><thead><tr><th>Field</th><th>Type</th></tr></thead><tbody><tr><td>country</td><td>string</td></tr><tr><td>region</td><td>string</td></tr><tr><td>city</td><td>string</td></tr><tr><td>postcode</td><td>string</td></tr><tr><td>address</td><td>string</td></tr></tbody></table>

---

### agreements

```json
{
  "agreements": [
    {
      "label": "Terms and Conditions",
      "ip": "127.0.0.1",
      "signedAt": "2026-01-01T12:00:00Z"
    }
  ]
}

```

<table id="bkmrk-field-type-descripti"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>label</td><td>string</td><td>Agreement name</td></tr><tr><td>ip</td><td>string</td><td>Signing IP</td></tr><tr><td>signedAt</td><td>string</td><td>ISO date</td></tr></tbody></table>

---

## 📤 Responses

### ✅ Success — With Autologin

```json
{
  "id": "user-uuid",
  "url": "https://your-domain/autologin/uuid/"
}

```

- URL allows **instant login**
- Valid for a **short time only**

---

### ✅ Success — Without Autologin

```json
{
  "id": "user-uuid"
}

```

---

## ❌ Error Responses

### 400 — Invalid Request

```json
{
  "message": "Email, phone and first name are required",
  "providerStatus": 400
}

```

---

### 401 — Unauthorized

```json
{
  "message": "Invalid secret key",
  "providerStatus": 401
}

```

---

### 500 — Server Error

```json
{
  "message": "Internal server error",
  "providerStatus": 500
}

```

---

## 📡 Example Requests

### Basic Registration

```bash
curl -X POST "https://your-domain/tradersroom/api/auth/signup" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "Jane"
  }'

```

---

### Full Example

```bash
curl -X POST "https://your-domain/tradersroom/api/auth/signup" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "Jane",
    "lastName": "Doe",
    "affiliateID": "AFF-123",
    "subID": "SUB-1",
    "campaignId": "CMP-456",
    "sourceId": "facebook_ads",
    "project": "default",
    "desk": "sales",
    "sendEmail": true
  }'

```

---

## ⚠️ Important Notes

- Each request creates a **new user**
- Email should be **unique**
- Autologin link is **temporary**
- Store returned `id` in your system
- API key must be kept **secure**
- Some system fields are **automatically managed** and cannot be overridden

---

## 📊 Recommended Integration Flow

1. Collect user data
2. Call Sign Up API
3. Handle response:
    
    
    - If `url` exists → redirect user
    - Otherwise → show success message
4. Store user ID