# Identity

## Endpoint

#### <https://api.dfend.app/identity>

Accepts requests from server environments only (secret API key).

## Methods

### GET

Retrieve the Identity for a user.

#### Accepts

`body`  <mark style="color:blue;">object</mark>  An object containing **one of the following** fields:

* `userId`  <mark style="color:blue;">string</mark>  The user's primary key or unique ID in your system.
* `id`  <mark style="color:blue;">string</mark>  The `id` value of the user's [Identity](https://dfend.gitbook.io/documentation/developer-api/types/identity) in DFend.

#### Returns

A JSON-encoded [Identity](https://dfend.gitbook.io/documentation/developer-api/types/identity) object.

### POST

Register an identity for a user.

#### Accepts

`body`  <mark style="color:blue;">object</mark>  An object containing the following fields:

* `userId`  <mark style="color:blue;">string</mark>  The user's primary key or unique ID in your system.
* `email`  <mark style="color:blue;">string optional</mark>  The user's email address. Must be a valid email address.
* `phone`  <mark style="color:blue;">string optional</mark>  The user's phone number. Must be in [E. 164 format](https://www.twilio.com/docs/glossary/what-e164).
* `merge`  <mark style="color:blue;">boolean optional</mark>  Update an existing Identity with this data if one exists.
* `metadata`  <mark style="color:blue;">object optional</mark>  Custom metadata you wish to add to this Identity.

{% hint style="warning" %}
If you are using any partner integrations, please be sure to merge the email address a user uses with the integration provider into the Identity you created for them in any other application or service to avoid duplicate Identities.
{% endhint %}

{% hint style="info" %}
We will not contact the user outside of the parameters you set within our system. Our platform is end-to-end encrypted using AES-256 and we will otherwise only use contact information for matching purposes in our detection algorithms.
{% endhint %}

#### Returns

A JSON-encoded object containing the following fields:

* `id`  <mark style="color:blue;">string</mark>  The user's Identity ID under your account on DFend.
* `created`  <mark style="color:blue;">boolean</mark>  Whether a new Identity was created.
* `merged`  <mark style="color:blue;">boolean</mark>  Whether an existing Identity was updated.

{% hint style="warning" %}
You **must** add the `id` field to the connected user's data in your system. This is the only way you will be able to match [Events](https://dfend.gitbook.io/documentation/developer-api/types/event) to your users.
{% endhint %}