# 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](/documentation/developer-api/types/identity.md) in DFend.

#### Returns

A JSON-encoded [Identity](/documentation/developer-api/types/identity.md) 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](/documentation/developer-api/types/event.md) to your users.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dfend.gitbook.io/documentation/developer-api/https-api/identity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.