> For the complete documentation index, see [llms.txt](https://support.emarketeer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.emarketeer.com/references/apis-developer/custom-signals-api.md).

# Custom Signals API

API reference: <https://api-doc.emarketeer.com/?urls.primaryName=Engagement>

***

Contacts in eMarketeer consist of three main parts:

* Contact fields
* Engagement
* Legal basis (consent)

Engagement records every interaction a contact makes with campaign components such as emails, forms, and landing pages. These interactions appear on the contact timeline and can be used to set lead score, trigger Journeys, and more. They give a 360-degree view of what the contact has interacted with over time.

<div align="left" data-with-frame="true"><img src="/files/hH0P08AHb0czp4lKbG1N" alt="contact timeline showing engagement events"></div>

### Custom Signals

With the Custom Signals API you can send contact events from any other system into eMarketeer, as long as you have the contact's email address. These signals are added as timeline events on the contact and can be used in filters, scoring, Journeys, and lead generation.

In the following scenario, you have an arcade game called "Space Invaders". Each time someone plays the game, you want to record the event in eMarketeer. You could then trigger Journeys based on different criteria — for example, send an email to anyone who scores over 100.

<div align="left" data-with-frame="true"><img src="/files/WorjgWDIavdUG0O0HNpX" alt="Space Invaders game played event on contact timeline"></div>

<div align="left" data-with-frame="true"><img src="/files/FRrSNSu74sCNqZIDlrDd" alt="event data fields shown in the contact filter"></div>

### The custom signals structure

To send the example above as a signal through the API, you would use this payload. The parameters are explained below.

```
{
  "adapter": "Space Invaders",
  "category": "Game Played",
  "eventData": {
    "Player Name": "Parzival",
    "Reached Level": "8",
    "Score": "10"
  },
    "contact": {
        "firstName": "Tye",
        "lastName": "Sheridan",
        "email": "tye@playerone.com",
        "company": "Oasis"
  },
  "eventTime": "2023-12-13T10:06:42.375Z",
    "consent": {
    "marketing": {
      "allowed": true,
      "text": "I agree to emails"
    }
  }
}
```

A custom signal has the following main parts.

**Adapter**

The top-level name of the signal. It is listed directly under "Engagement" in the filter.

<div align="left" data-with-frame="true"><img src="/files/Z5F9Y5vwEF4GC2GFLFF3" alt="adapter name listed under Engagement in the filter"></div>

Keep the number of distinct adapter names to a minimum, since all distinct adapter names appear directly under Engagement. A good practice is to use the service name of the signals you are sending. An adapter can then send multiple types of events.

In this example, the adapter name is "Space Invaders".

**Category**

The "verb" of the signal. In the Space Invaders example, possible categories include:

* Game played
* Inserted coins
* Got high score

<div align="left" data-with-frame="true"><img src="/files/sJxdCOjZ2hZ2rup6X1Nv" alt="signal categories shown under the selected adapter"></div>

In the filter, once you select the adapter name "Space Invaders", you see the categories of signals you have sent for that adapter.

**Event data**

You can send any information you need with the signal. In this case, the "Game played" signal carries Player Name, Reached Level, and Score. All of these can be used in the contact filter to find contacts who played the game and reached a certain score or level.

<div align="left" data-with-frame="true"><img src="/files/FRrSNSu74sCNqZIDlrDd" alt="event data fields used in the contact filter"></div>

**Contact data**

All signals must be assigned to a contact. At minimum, you need an email address, but you can send any standard or custom field to the contact card to create or update the contact.

**Consent (optional)**

You can also send legal basis data for marketing emails along with the signal.

**Event Time**

The timestamp you want for the event in the timeline. Send it as Zulu time (UTC).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://support.emarketeer.com/references/apis-developer/custom-signals-api.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.