# Civilian Integration

{% hint style="warning" %}
This submodule utilizes API endpoints that require the **plus** version of Sonoran CAD or higher. For more information, view our [pricing ](https://docs.sonoransoftware.com/cad/pricing/faq)page.
{% endhint %}

{% hint style="success" %}
Looking for VPS, web, or dedicated hosting? Check out our official [server hosting](https://docs.sonoransoftware.com/cad/integration-plugins/in-game-integration/fivem-installation/available-plugins/broken-reference)!
{% endhint %}

This submodule allows players to fetch their character information from the CAD. Basic functionality is provided with the /showid command, but developers are encouraged to use the export for their own creations.

![Sonoran CAD - Civilian Integration Lookup](https://232668649-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4pGN81fb4R6zFhodcu%2F-MOPTIWlR4AAhf0p2ug3%2F-MOPTPqbq-qn-RAlkQr9%2FScreen%20Shot%202020-12-12%20at%2010.00.21%20PM.png?alt=media\&token=36f83200-c8e5-4dc7-bfa8-df92e42bdf72)

## Activation Guide

### 1. Download and Install the Core

If you haven't already, be sure to install and configure the [SonoranCAD Core](https://docs.sonoransoftware.com/cad/integration-plugins/in-game-integration/fivem-installation) first.

### 2. Activate the Submodule and all Dependencies

1. Follow the [submodule activation guide](https://docs.sonoransoftware.com/cad/integration-plugins/in-game-integration/submodule-configuration#activating-a-submodule) for the `civintegration`, and `locations` submodules.

### 3. Set Your API ID

Don't forget to set your account [API ID](https://docs.sonoransoftware.com/cad/api-integration/getting-started/setting-your-api-id) to properly link your in-game user to the CAD.

## Further Configuration

| Option         | Description                                                                                                                                                                                                                                                                             | Default Value |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| cacheTime      | Time to cache characters in seconds                                                                                                                                                                                                                                                     | 3600          |
| allowCustomIds | Allow players to use /setid to set a custom name.                                                                                                                                                                                                                                       | true          |
| allowPurge     | Allow players to use /refreshid to "purge" their character list from cache.                                                                                                                                                                                                             | true          |
| enableIDCardUI | <p><strong>Recommended</strong>: Allows for a more realistic identification ui with /showid<br><br><strong>IF USING:</strong> Please ensure you start the resource <code>sonoran\_idcard</code> <strong>BEFORE</strong> <code>sonorancad</code> in your server resource start order</p> | false         |

## Usage

### Commands

The submodule comes with a few basic commands to show off the functionality.

<table data-header-hidden><thead><tr><th width="184.59915045830542">Command</th><th>Description</th></tr></thead><tbody><tr><td>Command</td><td>Description</td></tr><tr><td>/showid [id]</td><td>Shows the current ID of the specified player ID. If not specified, will show the current player's ID. Currently, it is displayed only to the calling client.</td></tr><tr><td>/setid</td><td>Sets a custom ID (first/last name, and date of birth). Overrides the currently selected CAD ID. Can be disabled in configuration.</td></tr><tr><td>/resetid</td><td>Resets the custom ID specified above.</td></tr><tr><td>/refreshid</td><td>Removes the "cached" characters for the client. This allows players to swap characters in the CAD without relogging or waiting for the cache timer.</td></tr></tbody></table>

### Export

You can use this export to fetch all characters for a specific player ID. This is a server-side export only.

```lua
Function: "GetCharacters"
Parameters:
    player: the player ID
    callback: function to call after fetching the data. Returns an array of character objects.

Example:
    exports["sonorancad"]:GetCharacters(playerId, function(result)
        -- do stuff with result, an array of character objects
    end)
```

This function can also be used in other submodules (without the export bit).