> For the complete documentation index, see [llms.txt](https://docs.imperialcad.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.imperialcad.app/api-and-integrations/api-integrations/api-endpoints-and-exports/imperial-characters-api-and-exports.md).

# Imperial Characters API & Exports

The ImperialCharacters module allows a FiveM server to create, retrieve, and delete characters or vehicles in ImperialCAD using exports and backend API calls.

***

### ⚙️ Setup

Add the following to your `server.cfg`:

```bash
setr imperial_community_id "YOUR_COMMUNITY_ID"
set imperialAPI "YOUR_API_SECRET"
```

Enable debug output:

```lua
Config.debug = true
```

***

### 📤 Exports & Examples

***

#### 🔹 `NewCharacter(data, callback)`

Creates a new civilian character in CAD.

**Required Fields**

| Field            | Type   | Description                                                                                |
| ---------------- | ------ | ------------------------------------------------------------------------------------------ |
| users\_discordID | string | Discord ID of the player(This allows them to still edit and interact with API made char's) |
| Fname            | string | First name                                                                                 |
| Mname            | string | Middle name                                                                                |
| Lname            | string | Last name                                                                                  |
| Birthdate        | string | Format: `YYYY-MM-DD`                                                                       |
| gender           | string | "Male", "Female", etc.                                                                     |
| race             | string | Race/ethnicity                                                                             |
| hairC            | string | Hair color                                                                                 |
| eyeC             | string | Eye color                                                                                  |
| height           | string | e.g., `"6'0"`                                                                              |
| weight           | string | e.g., `"180"`                                                                              |
| postal           | string | Postal code                                                                                |
| address          | string | Street address                                                                             |
| city             | string | City                                                                                       |
| county           | string | County                                                                                     |
| phonenum         | string | Phone number                                                                               |
| dlstatus         | string | e.g., `"Valid"` or `"Suspended"`                                                           |
| citizenid        | string | Unique character ID                                                                        |

**Example Usage**

```lua
exports["ImperialCAD"]:NewCharacter({
  users_discordID = "123456789012345678",
  Fname = "John",
  Mname = "T",
  Lname = "Doe",
  Birthdate = "1995-03-21",
  gender = "Male",
  race = "White",
  hairC = "Black",
  eyeC = "Brown",
  height = "6'1",
  weight = "190",
  postal = "202",
  address = "124 Grove St",
  city = "Los Santos",
  county = "Los Santos",
  phonenum = "5553331234",
  dlstatus = "Valid",
  citizenid = "JD321"
}, function(success, res)
  if success then print("Civilian created!") else print("Failed:", res) end
end)
```

**Example Response**

```lua
{
  "status": "success",
  "response": {
    "ssn": 684699354,
    "DLN": "D78239341",
    "age": 30,
    "name": " John T Doe"
  }
}
```

***

#### 🔹 `NewCharacterAdvanced(data, callback)`

Same as `NewCharacter` but supports license and misc details.

**Additional Fields**

```lua
licensedetails = {
  hasBoatLic = true,
  hasCDL = true,
  CDLNumber = "CDL1234",
  CDLStatus = "Valid",
  hasDL = true,
  DLNumber = "D1234567",
  DLStatus = "Valid",
  hasFirearmsCertification = true,
  hasFishLic = false,
  hasHuntLic = true
},
misc = {
  missing = false
}
```

**Example**

```lua
exports["ImperialCAD"]:NewCharacterAdvanced({
  Fname = "Jane",
  Mname = "A",
  Lname = "Smith",
  Birthdate = "1990-07-15",
  gender = "Female",
  race = "Hispanic",
  hairC = "Blonde",
  eyeC = "Green",
  height = "5'7",
  weight = "145",
  postal = "404",
  address = "555 Clinton Ave",
  city = "Los Santos",
  county = "Blaine",
  state = "San Andreas",
  phonenum = "5558881212",
  licensedetails = {
    hasBoatLic = false,
    hasCDL = true,
    CDLNumber = "CDL5678",
    CDLStatus = "Valid",
    hasDL = true,
    DLNumber = "D7894561",
    DLStatus = "Valid",
    hasFirearmsCertification = true,
    hasFishLic = true,
    hasHuntLic = true
  },
  misc = {
    missing = false
  }
}, function(success, res)
  if success then print("Advanced character created!") else print("Failed:", res) end
end)
```

**Example Response**

```lua
{
  "status": "success",
  "response": {
    "ssn": 684699354,
    "DLN": "D7894561",
    "age": 35,
    "name": "Jane A Smith"
  }
}
```

***

#### 🔹 `DeleteCharacter(data, callback)`

Deletes a character from CAD.

**Required Fields**

| Field            | Type   |
| ---------------- | ------ |
| users\_discordID | string |
| citizenid        | string |

**Example**

```lua
exports["ImperialCAD"]:DeleteCharacter({
  users_discordID = "123456789012345678",
  citizenid = "JD321"
}, function(success, res)
  if success then print("Character deleted.") else print("Failed to delete character:", res) end
end)
```

**Example Response**

```lua
{
  "status": "SUCCESS",
  "message": "Civilian and relevant data was marked to be deleted"
}
```

***

#### 🔹 `GetCharacter(charid, commId, callback)`

Retrieves a character by ID.

**Parameters**

| Param  | Type   | Description       |
| ------ | ------ | ----------------- |
| charid | string | Citizen ID        |
| commId | string | Your community ID |

**Example**

```lua
exports["ImperialCAD"]:GetCharacter("JD321", "myCommIdHere", function(success, data)
  if success then print(json.encode(data)) else print("Failed:", data) end
end)
```

**Example Response**

```lua
{
  "status": "success",
  "response": {
    "charid": "JD321",
    "name": "Jane A Smith",
    "ssn": "123456789",
    "age": "35",
    "address": "000 No Where Rd"
  }
}
```

***

#### 🔹 `GetCharacterAdvanced({ firstname, lastname }, callback)`

Searches by name.

**Parameters**

| Field     | Type   |
| --------- | ------ |
| firstname | string |
| lastname  | string |

**Example**

<pre class="language-lua"><code class="lang-lua"><strong>exports["ImperialCAD"]:GetCharacterAdvanced({
</strong>  firstname = "Jane",
  lastname = "Smith"
}, function(success, data)
  if success then print(json.encode(data)) else print("❌ Failed:", data) end
end)
</code></pre>

**Example Response**

```lua
{
  "status": "success",
  "response": {
    "charid": "JD321",
    "name": "Jane A Smith",
    "ssn": "123456789",
    "age": "35",
    "address": "000 No Where Rd"
  }
}
```

***

#### 🔹 `CreateVehicle(data, callback)`

Basic vehicle registration.

**Required Fields**

| Field | Type   | Required                       |
| ----- | ------ | ------------------------------ |
| ssn   | string | ✅                              |
| plate | string | ✅                              |
| model | string | ✅                              |
| color | string | ✅                              |
| year  | string | Optional (default `"2015"`)    |
| make  | string | Optional (default `"UNKNOWN"`) |

**Example**

```lua
exports["ImperialCAD"]:CreateVehicle({
  ssn = "JD321",
  plate = "ABC123",
  model = "Charger",
  color = "Black",
  year = "2022",
  make = "Dodge"
}, function(success, res)
  if success then print("Vehicle registered.") else print("❌ Failed:", res) end
end)
```

**Example Response**

```lua
{
  "status": "success",
  "response": {}
}
```

***

#### 🔹 `CreateVehicleAdvanced(data, callback)`

Detailed vehicle registration with owner & insurance.

**Required Format**

```lua
{
  vehicleData = {
    plate = "XYZ123",
    model = "Sultan RS",
    Make = "Karin",
    color = "Gray",
    year = "2021",
    regState = "SA",
    regStatus = "Valid",
    regExpDate = "2025-05-01",
    vin = "1HGCM82633A004352",
    stolen = false
  },
  vehicleInsurance = {
    hasInsurance = true,
    insuranceStatus = "Active",
    insurancePolicyNum = "INS234"
  },
  vehicleOwner = {
    ownerSSN = "JD321", --Attaching a valid SSN will allow us to link the vehicle to the civilian char
    ownerFirstName = "Jane",
    ownerLastName = "Smith",
    ownerGender = "Female",
    ownerAddress = "123 Main St",
    ownerCity = "Los Santos"
  }
}
```

**Example**

```lua
exports["ImperialCAD"]:CreateVehicleAdvanced({
  vehicleData = {
    plate = "XYZ123",
    model = "Sultan RS",
    Make = "Karin",
    color = "Gray",
    year = "2021",
    regState = "SA",
    regStatus = "Valid",
    regExpDate = "2025-05-01",
    vin = "1HGCM82633A004352",
    stolen = false
  },
  vehicleInsurance = {
    hasInsurance = true,
    insuranceStatus = "Active",
    insurancePolicyNum = "INS234"
  },
  vehicleOwner = {
    ownerSSN = "JD321",
    ownerFirstName = "Jane",
    ownerLastName = "Smith",
    ownerGender = "Female",
    ownerAddress = "123 Main St",
    ownerCity = "Los Santos"
  }
}, function(success, res)
  if success then print("Vehicle registered.") else print("Failed:", res) end
end)
```

**Example Response**

```lua
{
  "status": "success",
  "response": {
    "charid": "JD321",
    "name": "Jane A Smith",
    "ssn": "123456789",
    "age": "35",
    "address": "000 No Where Rd"
  }
}
```

***

### 🔗 API Reference

All API's will use the same format of "<https://imperialcad.app/api/1.1/wf/>" and then the provided API Endpoint as provided below.

`TYPE` `https://imperialcad.app/api/1.1/wf/<API_GOES_HERE>`

<table><thead><tr><th width="81">Type</th><th width="231">Export</th><th width="470">API Endpoint</th></tr></thead><tbody><tr><td><strong>POST</strong></td><td><code>NewCharacter</code></td><td><code>NewCharacter</code></td></tr><tr><td><strong>POST</strong></td><td><code>NewCharacterAdvanced</code></td><td><code>NewAdvancedCharacter</code></td></tr><tr><td><strong>POST</strong></td><td><code>DeleteCharacter</code></td><td><code>DeleteCharacter</code></td></tr><tr><td><strong>GET</strong></td><td><code>GetCharacter</code></td><td><code>GetCharacter</code></td></tr><tr><td><strong>GET</strong></td><td><code>GetCharacterAdvanced</code></td><td><code>GetCharacterAdvanced</code></td></tr><tr><td><strong>POST</strong></td><td><code>CreateVehicle</code></td><td><code>registerVehicle</code></td></tr><tr><td><strong>POST</strong></td><td><code>CreateVehicleAdvanced</code></td><td><code>registeradvancedvehicle</code></td></tr></tbody></table>

***

### 🔐 API Authorization

All `POST` endpoints require the following header:

```json
{
  "Content-Type": "application/json",
  "APIKEY": GetConvar("imperialAPI", "")
}
```

***

### 📎 License

© Imperial Solutions. Unauthorized distribution or use is prohibited.
