# Signal

## **Endpoint**

#### \*\*<https://api.dfend.app**/signal>

Accepts requests from client or server environments (publishable or secret API key).

## Methods

### POST

Send a [Signal](https://dfend.gitbook.io/documentation/developer-api/types/signal). Some fields will only be accepted from a server environment.

{% hint style="info" %}
When using your secret API key, we will create Identities on the fly when we receive Signals with an unrecognized user ID.
{% endhint %}

#### Accepts (client environment)

`body`  <mark style="color:blue;">object</mark>  An object containing the following subset of [Signal](https://dfend.gitbook.io/documentation/developer-api/types/signal) fields that are suitable for sending from a client environment:

* `idempotencyKey`  <mark style="color:blue;">string optional</mark>  Prevent duplicate events by providing a unique key for this signal.
* `type`  <mark style="color:blue;">string optional</mark>  A custom string value representing the type of event.
* `source`  <mark style="color:blue;">enum</mark>  A string of value `'App' | 'Browser'`.
* `device`  <mark style="color:blue;">Device optional</mark>  An object of [Device](https://dfend.gitbook.io/documentation/developer-api/types/device) type.
* `identifiers`  <mark style="color:blue;">object</mark>  An object containing at least one of the following fields:
  * `userId`  <mark style="color:blue;">string</mark>  The user's primary key or unique ID in your system.
  * `identity`  <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.

#### Accepts (server environment)

`body`  <mark style="color:blue;">object</mark>  An object containing the following subset of [Signal](https://dfend.gitbook.io/documentation/developer-api/types/signal) fields that are suitable for sending from a server environment:

* `idempotencyKey`  <mark style="color:blue;">string optional</mark>  Prevent duplicate events by providing a unique key for this signal.
* `type`  <mark style="color:blue;">string optional</mark>  A custom string value representing the type of event.
* `source`  <mark style="color:blue;">enum</mark>  A string of value `'Server'`.
* `device`  <mark style="color:blue;">Device optional</mark>  An object of [Device](https://dfend.gitbook.io/documentation/developer-api/types/device) type.
* `identifiers`  <mark style="color:blue;">object</mark>  An object containing at least one primary and any secondary [Identifiers](https://dfend.gitbook.io/documentation/developer-api/types/identifiers).
* `ip`  <mark style="color:blue;">string</mark>  The user's client IP address from the original request you received.
* `userAgent`  <mark style="color:blue;">string optional</mark>  The user's client user-agent from the original request you received.
* `lat`  <mark style="color:blue;">number optional</mark>  The latitude coordinate, if you obtained it from the user's device.
* `lon`  <mark style="color:blue;">number optional</mark>  The longitude coordinate, if you obtained it from the user's device.
* `metadata`  <mark style="color:blue;">object optional</mark>  Custom metadata you wish to add to this Signal.
* `time`  <mark style="color:blue;">number optional</mark>  A Unix timestamp (ms) representing the original time of Signal event.

#### Returns

A JSON-encoded object containing the following fields:

* `started`  <mark style="color:blue;">number</mark>  A Unix timestamp (ms).
* `finished`  <mark style="color:blue;">number</mark>  A Unix timestamp (ms).
* `immediateResults`  <mark style="color:blue;">ImmediateResult\[]</mark>  An array of [ImmediateResult](https://dfend.gitbook.io/documentation/developer-api/types/immediateresult) objects.