Identity

Create or retrieve an Identity object.

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 object An object containing one of the following fields:

• userId string The user's primary key or unique ID in your system.

• id string The id value of the user's Identity in DFend.

Returns

A JSON-encoded Identity object.

POST

Register an identity for a user.

Accepts

body object An object containing the following fields:

• userId string The user's primary key or unique ID in your system.

• email string optional The user's email address. Must be a valid email address.

• phone string optional The user's phone number. Must be in E. 164 format.
• merge boolean optional Update an existing Identity with this data if one exists.

• metadata object optional Custom metadata you wish to add to this Identity.

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.

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.

Returns

A JSON-encoded object containing the following fields:

• id string The user's Identity ID under your account on DFend.

• created boolean Whether a new Identity was created.

• merged boolean Whether an existing Identity was updated.

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 to your users.