> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Log LinkedIn and email conversation activity to your CRM

<Card title="Your Implementation Required" icon="triangle-exclamation" color="#f59e0b">
  This endpoint must be implemented on **your server**
</Card>

Enginy logs conversation activity (LinkedIn messages, InMails, connection requests, and emails) to your Custom CRM. Implement this endpoint so Enginy can create activity records whenever a message is sent or received.

***

## When Activities Are Created

Enginy creates activity records when:

| Event                       | Activity Type         | Direction  |
| --------------------------- | --------------------- | ---------- |
| LinkedIn message sent       | `LINKEDIN`            | `OUTBOUND` |
| LinkedIn message received   | `LINKEDIN`            | `INBOUND`  |
| LinkedIn InMail sent        | `LINKEDIN_INMAIL`     | `OUTBOUND` |
| LinkedIn InMail received    | `LINKEDIN_INMAIL`     | `INBOUND`  |
| Connection request sent     | `LINKEDIN_CONNECTION` | `OUTBOUND` |
| Connection request accepted | `LINKEDIN_CONNECTION` | `INBOUND`  |
| Email sent                  | `EMAIL`               | `OUTBOUND` |
| Email received              | `EMAIL`               | `INBOUND`  |

<Info>
  Activities are only logged for campaigns with message sync enabled. Configure this in your campaign
  settings.
</Info>

***

## Subject Format

Enginy formats the `subject` field to provide context about the message:

**Outbound messages** (from your team):

```
[{sequenceIndex}/{sequenceCount}] [FROM {YourCompany}] {SenderName}
```

Example: `[1/3] [FROM Acme Corp] John Smith`

**Inbound messages** (from the contact):

```
[{ContactCompany}] {ContactFirstName} {ContactLastName}
```

Example: `[TechStartup Inc] Jane Doe`

<Tip>
  The sequence index (e.g., `[1/3]`) indicates this is message 1 of 3 in the sequence. This helps track
  campaign progress.
</Tip>

***

## Create Activity

Creates a new activity record in your CRM.

```http theme={null}
POST /activities
```

### Request Body

| Field        | Type              | Required | Description                                                                  |
| ------------ | ----------------- | -------- | ---------------------------------------------------------------------------- |
| `type`       | string            | Yes      | Activity type: `EMAIL`, `LINKEDIN`, `LINKEDIN_CONNECTION`, `LINKEDIN_INMAIL` |
| `subject`    | string            | No       | Activity subject/title                                                       |
| `body`       | string            | No       | Activity body or message content (may include HTML)                          |
| `direction`  | string            | No       | `INBOUND` or `OUTBOUND`                                                      |
| `ownerId`    | string            | No       | Owner/user ID in your CRM                                                    |
| `occurredAt` | string (ISO 8601) | No       | When the activity happened                                                   |
| `contactId`  | string            | No       | Associated contact/lead CRM ID                                               |
| `companyId`  | string            | No       | Associated company CRM ID                                                    |
| `metadata`   | object            | No       | Optional metadata (e.g., sequence index, message ID)                         |

<Info>
  Typical `metadata` keys include `messageId`, `sequenceIndex`, and `sequenceMessageCount`. You can store them
  for traceability or ignore them.
</Info>

### Example: Email Activity

```json theme={null}
{
  "type": "EMAIL",
  "subject": "[1/3] Re: Partnership Opportunity",
  "body": "<div>Hi Jane, Thanks for your interest...</div>",
  "direction": "OUTBOUND",
  "ownerId": "user-123",
  "occurredAt": "2024-12-31T10:00:00Z",
  "contactId": "contact-456",
  "companyId": "company-789",
  "metadata": {
    "sequenceIndex": 1,
    "sequenceMessageCount": 3,
    "messageId": "msg-abc123"
  }
}
```

### Example: LinkedIn Outbound Message

```json theme={null}
{
  "type": "LINKEDIN",
  "subject": "[1/3] [FROM Acme Corp] John Smith",
  "body": "Hi Jane, I noticed your company is expanding...",
  "direction": "OUTBOUND",
  "ownerId": "user-123",
  "occurredAt": "2024-12-31T10:00:00Z",
  "contactId": "contact-456",
  "companyId": "company-789",
  "metadata": {
    "messageId": "linkedin-msg-123",
    "sequenceIndex": 1,
    "sequenceMessageCount": 3
  }
}
```

### Example: LinkedIn Inbound Reply

```json theme={null}
{
  "type": "LINKEDIN",
  "subject": "[TechStartup Inc] Jane Doe",
  "body": "Thanks for reaching out. Happy to chat!",
  "direction": "INBOUND",
  "ownerId": "user-123",
  "occurredAt": "2024-12-31T11:00:00Z",
  "contactId": "contact-456",
  "companyId": "company-789",
  "metadata": {
    "messageId": "linkedin-msg-456"
  }
}
```

### Response

Return the created activity with at least an `id` field:

```json theme={null}
{
  "id": "activity-abc123",
  "type": "EMAIL",
  "subject": "[1/3] Re: Partnership Opportunity",
  "direction": "OUTBOUND",
  "occurredAt": "2024-12-31T10:00:00Z"
}
```

<Warning>
  The `id` field is **required** in the response. Enginy stores this ID to prevent duplicate activity logs.
</Warning>

***

## Activity Schema Reference

| Field        | Type              | Required       | Description                                                   |
| ------------ | ----------------- | -------------- | ------------------------------------------------------------- |
| `id`         | string            | Yes (response) | Unique identifier for the activity                            |
| `type`       | string            | Yes            | `EMAIL`, `LINKEDIN`, `LINKEDIN_CONNECTION`, `LINKEDIN_INMAIL` |
| `subject`    | string            | No             | Activity subject/title                                        |
| `body`       | string            | No             | Activity body/content (may contain HTML)                      |
| `direction`  | string            | No             | `INBOUND` or `OUTBOUND`                                       |
| `ownerId`    | string            | No             | Assigned user ID                                              |
| `occurredAt` | string (ISO 8601) | No             | Timestamp of the activity                                     |
| `contactId`  | string            | No             | Associated contact/lead CRM ID                                |
| `companyId`  | string            | No             | Associated company CRM ID                                     |
| `metadata`   | object            | No             | Additional metadata                                           |

***

## Testing Your Activities API

<Steps>
  <Step title="Test Email Activity">
    ```bash theme={null}
    curl -X POST https://your-api.com/activities \
      -H "X-API-Key: your-secret-key" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "EMAIL",
        "subject": "Test email activity",
        "direction": "OUTBOUND",
        "contactId": "contact-123"
      }'
    ```
  </Step>

  <Step title="Test LinkedIn Activity">
    ```bash theme={null}
    curl -X POST https://your-api.com/activities \
      -H "X-API-Key: your-secret-key" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "LINKEDIN",
        "subject": "[1/3] [FROM Acme] John Smith",
        "body": "Hi, I wanted to connect...",
        "direction": "OUTBOUND",
        "contactId": "contact-123"
      }'
    ```
  </Step>

  <Step title="Verify Response">
    Ensure your response includes an `id` field:

    ```json theme={null}
    {
      "id": "activity-xyz789"
    }
    ```
  </Step>
</Steps>

***

## Reference Implementation

<Card title="GitHub Repository" icon="github" href="https://github.com/Genesy-AI/custom-crm-example">
  See a complete working implementation of the activities endpoint, including how to display activities in
  contact/company detail pages.
</Card>