Contacts

Note

此页面的内容需要进行重大更新。旧页面包含过时且可能不准确的信息。您仍然可以在 Mautic Developer Documentation archived repository 中访问它。

如果您有兴趣帮助开发此页面和其他页面的新内容，请考虑加入文档编写工作。

请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始您的贡献。

使用此端点来操作和获取有关 Mautic 联系人的详细信息。

使用 Mautic API 库

您可以通过以下方式使用 Mautic API Library 与此 API 进行交互，或者使用本文档中描述的各种 HTTP 端点。

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth   = new ApiAuth();
$auth       = $initAuth->newAuth($settings);
$apiUrl     = "https://example.com";
$api        = new MauticApi();
$contactApi = $api->newApi("contacts", $auth, $apiUrl);

获取联系人

<?php

//...
$contact = $contactApi->get($id);

获取单个具有 ID 的联系人。

HTTP 请求

GET /contacts/ID

响应

Expected Response Code: 200

“contact”: {

“id”: 47, “dateAdded”: “2015-07-21T12:27:12-05:00”, “createdBy”: 1, “createdByUser”: “Joe Smith”, “dateModified”: “2015-07-21T14:12:03-05:00”, “modifiedBy”: 1, “modifiedByUser”: “Joe Smith”, “owner”: {

“id”: 1, “Username”: “joesmith”, “firstName”: “Joe”, “lastName”: “Smith”

}, “points”: 10, “lastActive”: “2015-07-21T14:19:37-05:00”, “dateIdentified”: “2015-07-21T12:27:12-05:00”, “color”: “ab5959”, “ipAddresses”: {

“111.111.111.111”: {

“ipAddress”: “111.111.111.111”, “ipDetails”: {

“city”: “”, “region”: “”, “country”: “”, “latitude”: “”, “longitude”: “”, “isp”: “”, “organization”: “”, “timezone”: “”

}

}

}, “fields”: {

“core”: {

“title”: {

“id”: “1”, “label”: “Title”, “alias”: “title”, “type”: “lookup”, “group”: “core”, “value”: “Mr”

}, “firstname”: {

“id”: “2”, “label”: “First Name”, “alias”: “firstname”, “type”: “text”, “group”: “core”, “value”: “Jim”

},

“…”: {

“…” : “…”

}

}, “social”: {

“twitter”: {

“id”: “17”, “label”: “Twitter”, “alias”: “twitter”, “type”: “text”, “group”: “social”, “value”: “jimcontact”

},

“…”: {

“…” : “…”

}

}, “personal”: [], “professional”: [], “all”: {

“title”: “Mr”, “firstname”: “Jim”, “twitter”: “jimcontact”,

“…”: “…”

}

}

}

Contact Properties

• • Name

    • Type

    • Description

  • • id

    • int

    • ID of the Contact

  • • isPublished

    • boolean

    • true if the Contact has the status of published

  • • dateAdded

    • datetime

    • Date/time Contact got created

  • • createdBy

    • int

    • ID of the User that created the Contact

  • • createdByUser

    • string

    • Name of the User that created the Contact

  • • dateModified

    • datetime/null

    • Date/time Contact was last modified

  • • modifiedBy

    • int

    • ID of the User that last modified the Contact

  • • modifiedByUser

    • string

    • Name of the User that last modified the Contact

  • • owner

    • object

    • User object that owns the Contact.

  • • points

    • int

    • Contact’s current number of Points

  • • lastActive

    • datetime/null

    • Date/time for when the Contact was last recorded as active

  • • dateIdentified

    • datetime/null

    • Date/time when the Contact identified themselves

  • • color

    • string

    • Hex value given to Contact from Point Trigger definitions based on the number of Points the Contact got awarded

  • • ipAddresses

    • array

    • Array of IP addresses currently associated with this Contact

  • • fields

    • array

    • Array of all Contact fields with data grouped by field group. See JSON code example for format. This array includes an “all” key that includes an single level array of fieldAlias => ContactValue pairs.

  • • tags

    • array

    • Array of tags associated with this Contact. See JSON code example for format.

  • • utmtags

    • array

    • Array of UTM Tags associated with this Contact. See JSON code example for format.

  • • doNotContact

    • array

    • Array of Do Not Contact objects. See JSON code example for format.

List Contacts

<?php

//...
$contacts = $contactApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

获取联系人列表。

HTTP Request

GET /contacts

Query Parameters

• • Name

    • Description

  • • search

    • 用于过滤实体的字符串或搜索命令。

  • • start

    • 返回的实体起始行数。默认为 0。

  • • limit

    • 要返回的实体数量限制。默认为分页系统的配置值，默认值为 30。

  • • orderBy

    • 用于排序的列。可以使用响应中列出的任何列。但是，需要将响应中所有以 camelCase 形式编写的属性进行修改。在每个大写字母前添加一个下划线 _，并将大写字母转换为小写字母。例如，dateIdentified 变为 date_identified，modifiedByUser 变为 modified_by_user 等。

  • • orderByDir

    • 排序方向：asc 或 desc。

  • • publishedOnly

    • 仅返回当前已发布的实体。

  • • minimal

    • 仅返回实体的数组，不包含其他列表。

  • • where

    • 高级筛选条件数组。

  • • order

    • 高级排序语句数组。

  • • select

    • 要包含在联系人数据中的字段别名数组，其中 ID 字段是强制性的。如果未提供该参数，Mautic 将返回所有字段。

高级筛选

在某些情况下，您可能需要按特定值进行过滤。请使用如下所示的 URL 参数：

在 PHP 中：

$where = [
  [
    'col' => 'phone',
    'expr' => 'in',
    'val' => '444444444,888888888',
  ]
];

此设计允许在同一请求中添加多个条件。

如果您不使用 PHP，以下是示例的 URL 编码版本： GET https://[example.com]/api/contacts?where%5B0%5D%5Bcol%5D=phone&where%5B0%5D%5Bexpr%5D=in&where%5B0%5D%5Bval%5D=444444444,888888888

您可以在 Doctrine 的 ORM 网站 上找到可用表达式的列表。

响应

预期响应代码：200

{

“total”: “1”, “contacts”: {

“47”: {

“id”: 47, “isPublished”: true, “dateAdded”: “2015-07-21T12:27:12-05:00”, “createdBy”: 1, “createdByUser”: “Joe Smith”, “dateModified”: “2015-07-21T14:12:03-05:00”, “modifiedBy”: 1, “modifiedByUser”: “Joe Smith”, “owner”: {

“id”: 1, “Username”: “joesmith”, “firstName”: “Joe”, “lastName”: “Smith”

}, “points”: 10, “lastActive”: “2015-07-21T14:19:37-05:00”, “dateIdentified”: “2015-07-21T12:27:12-05:00”, “color”: “ab5959”, “ipAddresses”: {

“111.111.111.111”: {

“ipAddress”: “111.111.111.111”, “ipDetails”: {

“city”: “”, “region”: “”, “country”: “”, “latitude”: “”, “longitude”: “”, “isp”: “”, “organization”: “”, “timezone”: “”

}

}

}, “fields”: {

“core”: {

“title”: {

“id”: “1”, “label”: “Title”, “alias”: “title”, “type”: “lookup”, “group”: “core”, “value”: “Mr”

}, “firstname”: {

“id”: “2”, “label”: “First Name”, “alias”: “firstname”, “type”: “text”, “group”: “core”, “value”: “Jim”

},

“…”: {

“…” : “…”

}

}, “social”: {

“twitter”: {

“id”: “17”, “label”: “Twitter”, “alias”: “twitter”, “type”: “text”, “group”: “social”, “value”: “jimcontact”

},

“…”: {

“…” : “…”

}

}, “personal”: [], “professional”: [], “all”: {

“title”: “Mr”, “firstname”: “Jim”, “twitter”: “jimcontact”

“…”: “…”

}

}, “tags”: [{

“tag”: “aTag”

}, {

“tag”: “bTag”

}], “utmtags” : [{

“id”: 1, “query”: {

“page”: “asd”, “cid”: “fb1”

}, “referer”: “https://example.com/”, “remoteHost”: “example.com”, “UserAgent”: “Mozilla/5.0 (Windows NT 10.0; WOW64; rv:50.0) Gecko/20100101 Firefox/50.0”, “utmCampaign”: “abcampaign”, “utmContent”: “page”, “utmMedium”: “social”, “utmSource”: “fb”, “utmTerm”: “test1”

}], “doNotContact”: [{

“id”: 2, “reason”: 2, “comments”: “”, “channel”: “email”, “channelId”: null

}]

}

}

}

Properties

Same as Get Contact.

Create Contact

<?php

$data = array(
    'firstname' => 'Jim',
    'lastname'  => 'Contact',
    'email'     => 'jim@example.com',
    'ipAddress' => $_SERVER['REMOTE_ADDR'],
    'overwriteWithBlank' => true,
);

$contact = $contactApi->create($data);

Create a new Contact.

HTTP Request

POST /contacts/new

POST Parameters

Name	Description
*	You can post any Contact field alias as a parameter. For example, firstname, lastname, email, etc.
ipAddress	IP address to associate with the Contact
lastActive	Date/time in UTC; preferably in the format of Y-m-d H:m:i but if that format fails, the string get sent through PHP’s strtotime then formatted
owner	ID of a Mautic User to assign this Contact to
overwriteWithBlank	If true, then empty values get set to fields. Otherwise empty values get skipped

Response

Expected Response Code: 201

Properties

Same as Get Contact.

Create Batch Contact

<?php

$data = array(
    array(
    'firstname' => 'Jim',
    'lastname'  => 'Contact',
    'email'     => 'jim@example.com',
    'ipAddress' => $_SERVER['REMOTE_ADDR']
    ),
    array(
    'firstname' => 'Rudolf',
    'lastname'  => 'Große',
    'email'     => 'rudolf@example.com',
    'ipAddress' => $_SERVER['REMOTE_ADDR']
    )
);
$contact = $contactApi->createBatch($data);

Create a batch of new Contacts.

HTTP Request

POST /contacts/batch/new

Name	Description
*	您可以发布任何联系人字段的别名作为参数。例如，firstname、lastname、email 等。
ipAddress	与联系人关联的 IP 地址
lastActive	UTC 格式的时间；最好使用 Y-m-d H:m:i 格式，但如果该格式失败，则字符串将通过 PHP 的 strtotime 函数进行处理并进行格式化。
owner	要分配给此联系人的 Mautic 用户 ID

Response

`Expected Response Code: 201`

Properties

联系人数组。记录与 Get Contact 相同。

编辑联系人

<?php

$id   = 1;
$data = array(
    'email'     => 'isabel-new-address@example.com',
    'ipAddress' => $_SERVER['REMOTE_ADDR'],
);

// 如果 ID 为 1 的联系人不存在，则创建新的联系人吗？
$createIfNotFound = true;

$contact = $contactApi->edit($id, $data, $createIfNotFound);

编辑一个现有的联系人。请注意，这支持 PUT 或 PATCH，具体取决于所需的行为。

PUT 如果给定的 ID 不存在，则会创建一个联系人，并清除所有联系人的信息，然后添加来自请求的信息。 PATCH 如果具有给定 ID 的联系人不存在，则会失败，并且使用来自请求的值更新联系人字段值。

HTTP 请求

要编辑一个联系人，并在未找到该联系人时返回 404：

`PATCH /contacts/ID/edit`

要编辑一个联系人，如果未找到该联系人，则创建一个新的联系人：

`PUT /contacts/ID/edit`

POST 参数

Name	Description
*	您可以发布任何联系人字段的别名作为参数。例如，firstname、lastname、email 等。
ipAddress	与联系人关联的 IP 地址
lastActive	UTC 格式的时间；最好使用 Y-m-d H:m:i 格式，但如果该格式失败，则字符串将通过 PHP 的 strtotime 函数进行处理并进行格式化。
owner	要分配给此联系人的 Mautic 用户 ID
overwriteWithBlank	如果为 true，则空值将被设置为字段。否则，空值将被跳过

Response

如果使用 PUT，则预期的响应代码是 200`（如果已编辑联系人）或 `201`（如果已创建）。 如果使用 `PATCH，则预期的响应代码是 200。

Properties

与 Get Contact 相同。

Note

要从联系人中删除一个标签，请在该标签前添加减号 -。例如：tags: [‘one’, ‘-two’] - 将此发送到请求体将为联系人添加标签 one 并删除标签 two。

批量编辑联系人

$data = [

[

‘id’ => 1, ‘firstname’ => ‘Jim’, ‘lastname’ => ‘Contact’, ‘title’ => ‘’, // This will be ignored because overwriteWithBlank is false by default ‘email’ => ‘jim@example.com’, ‘ipAddress’ => $_SERVER[‘REMOTE_ADDR’]

], [

‘overwriteWithBlank’ => true, // This flag will allow you to overwrite any field with a blank value ‘id’ => 2, ‘firstname’ => ‘Ashish’, ‘lastname’ => ‘Wallach’, ‘title’ => ‘’, // This will set the title to blank because overwriteWithBlank is true ‘email’ => ‘ashish@example.com’, ‘ipAddress’ => $_SERVER[‘REMOTE_ADDR’]

]

];

$contact = $contactApi->editBatch($data);

Edit several Contacts in one request. Note that this supports PUT or PATCH depending on the desired behavior.

PUT creates a Contact if the given ID doesn’t exist and clears all the Contact information, adds the information from the request. PATCH fails if the Contact with the given ID doesn’t exist and updates the Contact field values with the values from the request.

HTTP Request

To edit a Contact and return a 404 if the Contact isn’t found:

PATCH /contacts/batch/edit

To edit a Contact and create a new one if the Contact isn’t found:

PUT /contacts/batch/edit

POST Parameters

Name	Description
*	You can post any Contact field alias as a parameter. For example, firstname, lastname, email, etc.
ipAddress	IP address to associate with the Contact
lastActive	Date/time in UTC; preferably in the format of Y-m-d H:m:i but if that format fails, the string get sent through PHP’s strtotime then formatted
owner	ID of a Mautic User to assign this Contact to
overwriteWithBlank	If true, then empty values get set to fields. Otherwise empty values get skipped

Response

If PUT, the expected response code is 200 if the Contact got edited or 201 if created. If PATCH, the expected response code is 200.

Properties

Contacts array. Record same as Get Contact.

Note

In order to remove a tag from the Contact, add minus - before it. For example: tags: ['one', '-two'] - sending this in request body will add tag one and remove tag two from Contact.

Delete Contact

<?php

$contact = $contactApi->delete($id);

Delete a Contact.

HTTP Request

DELETE /contacts/ID/delete

Response

Expected Response Code: 200

Properties

Same as Get Contact.

Delete Batch Contact

<?php
$data = array(1, 2);
$contact = $contactApi->deleteBatch($data);

删除联系人。

HTTP 请求

DELETE /contacts/batch/delete

如果您没有使用 PHP，以下是一个 URL 示例：

DELETE https://[example.com]/api/contacts/batch/delete?ids=1,2

响应

Expected Response Code: 200

属性

联系人数组。记录与 Get Contact 相同。

添加“禁止联系”

<?php

$contactApi->addDnc($contactId, $channel, $reason, $channelId, $comments);

将联系人添加到“禁止联系”列表

HTTP 请求

要向联系人添加一个“禁止联系”条目：

POST /contacts/ID/dnc/CHANNEL/add

数据参数（可选）

Name	Description
channel	“禁止联系”的渠道。例如“email”、“sms”等，默认为 email。
reason	原因的整数值。使用 Contacts 常量：Contacts::UNSUBSCRIBED (1), Contacts::BOUNCED (2), Contacts::MANUAL (3)。默认为 Manual
channelId	导致退订的实体的 ID
comments	描述“禁止联系”条目的详细信息的文本

响应

{
  "channelId": "26",
  "reason": "Integration issued DNC",
  "comments": "Unsubscribed via API"
}

从“禁止联系”中移除

<?php
$contactApi->removeDnc($contactId, $channel);

从“禁止联系”列表中移除一个联系人

HTTP 请求

要从联系人中移除“禁止联系”条目：

POST /contacts/ID/dnc/CHANNEL/remove

数据参数（可选）

Name	Description
channel	“禁止联系”的渠道。例如“email”、“sms”等，默认为 email。

响应

与 Get Contact 相同。

添加 UTM 标签

<?php

$data = array(
    'utm_campaign' => 'apicampaign',
    'utm_source'   => 'fb',
    'utm_medium'   => 'social',
    'utm_content'  => 'fbad',
    'utm_term'     => 'mautic api',
    'Useragent'    => 'Mozilla/5.0 (Windows NT 10.0; WOW64; rv:50.0) Gecko/20100101 Firefox/50.0',
    'url'          => '/product/fbad01/',
    'referer'      => 'https://google.com/q=mautic+api',
    'query'        => ['cid'=>'abc','cond'=>'new'], // or as string with "cid=abc&cond=new"
    'remotehost'   => 'example.com',
    'lastActive'   => '2017-01-17T00:30:08+00:00'
 );
$contactApi->addUtm($contactId, $data);

向联系人添加 UTM 标签

HTTP 请求

要向联系人添加一个 UTM 标签条目：

POST /contacts/ID/utm/add

UTM 参数 (必需)

Mautic 需要参数数组。每个 UTM 标签条目是可选的。

Name	Description
utm_campaign	UTM Campaign 参数
utm_source	UTM Source 参数
utm_medium	UTM Medium 参数
utm_content	UTM Content 参数
utm_term	UTM Term 参数
Useragent	浏览器的 UserAgent。如果提供，则在必要时会创建一个新的设备条目。
url	page URL
referer	推荐方的 URL。
query	您希望包含的任何其他查询参数。数组或 HTTP 查询字符串
remotehost	主机名
lastActive	执行操作的日期。如果包含，则会更新联系人的 lastActive 日期。需要日期格式 2017-01-17T00:30:08+00:00。

响应

与 Get Contact 相同，但包含添加的 UTM 标签。

从联系人中移除 UTM 标签

<?php
$contactApi->removeUtm($contactId, $utmId);

移除一组来自联系人的 UTM 标签

HTTP 请求

要从联系人中移除 UTM 标签：

POST /contacts/ID/utm/UTMID/remove

数据参数

无需提供。

响应

与 Get Contact 相同，但不包含已移除的 UTM 标签。

添加积分

<?php

$data = [
     'eventName' => 'Score via api',
     'actionName' => 'Adding',
];
$contactApi->addPoints($contactId, $pointDelta, $data);

添加联系人积分

HTTP 请求

要向联系人添加积分，如果未找到该联系人则返回 404：

POST /contacts/ID/points/plus/POINTS

数据参数 (可选)

Name	Description
eventName	事件名称
actionName	操作名称

响应

预期响应代码：200

{
    "success": true
}

减积分

<?php

$data = array(
     'eventname' => 'Score via api',
     'actionname' => 'Subtracting',
 );
$contactApi->subtractPoints($contactId, $pointDelta, $data);

减去联系人积分

HTTP 请求

要从联系人中减去积分，如果未找到该联系人则返回 404：

POST /contacts/ID/points/minus/POINTS

数据参数 (可选)

Name	Description
eventname	事件名称
actionname	操作名称

响应

预期响应代码：200

{

“success”: true

}

获取所有联系人组分值

获取特定联系人的所有分组分值。

HTTP 请求

GET /api/contacts/{leadId}/points/groups

响应

预期响应代码: 200

{
    "total": 1,
    "groupScores": [
        {
            "score": 21,
            "group": {
                "id": 6,
                "name": "A"
            }
        }
    ]
}

响应包含联系人的分组分值列表。

获取单个联系人组分值

获取特定联系人的特定分组的分值。

HTTP 请求

GET /api/contacts/{leadId}/points/groups/{groupId}

响应

预期响应代码: 200

{
    "groupScore": {
        "score": 21,
        "group": {
            "id": 6,
            "name": "A"
        }
    }
}

响应包含联系人的指定分组的分值。

添加联系人组分值

向特定联系人的特定分组增加积分。

HTTP 请求

POST /api/contacts/{leadId}/points/groups/{groupId}/plus/{value}

数据参数 (可选)

Name	Description
eventname	事件名称
actionname	操作名称

响应

预期响应代码: 200

{
    "groupScore": {
        "score": 21,
        "group": {
            "id": 6,
            "name": "A"
        }
    }
}

响应指示成功向联系人的指定分组添加积分。

减小联系人组分值

从特定联系人的特定分组减少积分。

HTTP 请求

POST /api/contacts/{leadId}/points/groups/{groupId}/minus/{value}

数据参数 (可选)

Name	Description
eventname	事件名称
actionname	操作名称

响应

预期响应代码: 200

{
    "groupScore": {
        "score": 21,
        "group": {
            "id": 6,
            "name": "A"
        }
    }
}

响应指示成功从联系人的指定分组减少积分。

设置联系人组分值

设置特定联系人的特定分组的分值。

HTTP 请求

POST /api/contacts/{leadId}/points/groups/{groupId}/set/{value}

Data Parameters (optional)

Name	Description
eventname	Name of the event
actionname	Name of the action

Response

Expected Response Code: 200

{
    "groupScore": {
        "score": 21,
        "group": {
            "id": 6,
            "name": "A"
        }
    }
}

The response indicates the success of setting the Points for the specified Point Group for the Contact.

Divide Contact Point Group score

将特定联系人的特定积分组的积分除以一个值。

HTTP Request

POST /api/contacts/{leadId}/points/groups/{groupId}/divide/{value}

Data Parameters (optional)

Name	Description
eventname	Name of the event
actionname	Name of the action

Response

Expected Response Code: 200

{
    "groupScore": {
        "score": 21,
        "group": {
            "id": 6,
            "name": "A"
        }
    }
}

The response indicates the success of dividing the Points of the specified Point Group for the Contact by the specified value.

Multiply Contact Point Group score

将特定联系人的特定积分组的积分乘以一个值。

HTTP Request

POST /api/contacts/{leadId}/points/groups/{groupId}/times/{value}

Data Parameters (optional)

Name	Description
eventname	Name of the event
actionname	Name of the action

Response

Expected Response Code: 200

{
    "groupScore": {
        "score": 21,
        "group": {
            "id": 6,
            "name": "A"
        }
    }
}

The response indicates the success of multiplying the Points of the specified Point Group for the Contact by the specified value.

List Available Owners

<?php

$owners = $contactApi->getOwners();

获取可用于在创建/编辑时将联系人分配给的负责人列表。

HTTP Request

GET /contacts/list/owners

Response

Expected Response Code: 200

[
  {
    "id": 1,
    "firstName": "Joe",
    "lastName": "Smith"
  },
  {
    "id": 2,
    "firstName": "Jane",
    "lastName": "Smith"
  }
]

Owner Properties

• • Name

    • Type

    • Description

  • • id

    • int

    • Mautic 用户 ID

  • • firstName

    • string

    • Mautic 用户的名

  • • lastName

    • string

    • Mautic 用户的姓

列出可用字段

<?php

$fields = $contactApi->getFieldList();

获取可用的联系人字段列表，包括自定义字段。

HTTP 请求

GET /contacts/list/fields

响应

预期响应代码: 200

{
    "1": {
        "id": 1,
        "label": "Title",
        "alias": "title",
        "type": "lookup",
        "group": "core",
        "order": 1
    },
    "2": {
        "id": 2,
        "label": "First Name",
        "alias": "firstname",
        "type": "text",
        "group": "core",
        "order": 2
    },
    "3": {
        "id": 3,
        "label": "Last Name",
        "alias": "lastname",
        "type": "text",
        "group": "core",
        "order": 3
    },

    "...": {
        "..." : "..."
    }
}

字段属性

Name	Type	Description
id	int	字段 ID
label	string	字段标签
alias	string	在数据库中用作列名的字段别名
type	string	字段类型，例如 text、lookup 等
group	string	字段所属的组
order	int	字段顺序

列出联系人备注

<?php

$notes = $contactApi->getContactNotes($id, $searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

获取特定联系人的备注列表。

HTTP 请求

GET /contacts/ID/notes

查询参数

Name	Description
search	用于过滤实体的字符串或搜索命令。
start	返回实体的起始行。默认为 0。
limit	要返回的实体数量限制。默认为分页系统的配置，默认值为 30。
orderBy	用于排序的列。可以使用响应中列出的任何列。
orderByDir	排序方向：asc 或 desc。

响应

预期响应代码: 200

{
    "total": 1,
    "notes": [
        {
              "id": 1,
              "text": "<p>Jim is super cool!</p>",
              "type": "general",
              "dateTime": "2015-07-23T13:14:00-05:00"
        }
    ]
}

备注属性

• • Name

    • Type

    • Description

  • • id

    • int

    • ID of the note

  • • text

    • string

    • Body of the note

  • • type

    • string

    • Type of note. Options are general, email, call, meeting

  • • dateTime

    • datetime

    • Date/time string of when the note got created.

Get Segment Memberships

<?php

$segments = $contactApi->getContactSegments($id);

Get a list of Contact Segments the Contact is a member of.

HTTP Request

GET /contacts/ID/segments

Response

Expected response code: 200

{
    "total": 1,
    "segments": {
        "3": {
            "id": 3,
            "name": "New Contacts",
            "alias": "newcontacts"
        }
    }
}

List Properties

Name	Type	Description
id	int	ID of the list
name	string	Name of the list
alias	string	Alias of the list used with search commands.
dateAdded	datetime	Date/time string for when the Contact got added to the list
manuallyAdded	boolean	true if the Contact was manually added to the list versus added by a filter
manuallyRemoved	boolean	true if the Contact was manually removed from the list even though the list’s filter is a match

Change List Memberships

See Segments.

Get Campaign Memberships

<?php

$campaigns = $contactApi->getContactCampaigns($id);

Get a list of Campaigns the Contact is a member of.

HTTP Request

GET /contacts/ID/campaigns

Response

Expected response code: 200

{
    "total": 1,
    "campaigns": {
        "1": {
            "id": 1,
            "name": "Welcome Campaign",
            "dateAdded": "2015-07-21T14:11:47-05:00",
            "manuallyRemoved": false,
            "manuallyAdded": false,
            "list_membership": [
                3
            ]
        }
    }
}

List Properties

• • Name

    • Type

    • Description

  • • id

    • int

    • Campaign 的 ID

  • • name

    • string

    • Campaign 的名称

  • • dateAdded

    • datetime

    • Contact 被添加到 Campaign 的日期/时间字符串

  • • manuallyAdded

    • boolean

    • 如果 Contact 是手动添加到 Campaign，则为 true；如果由 Contact 列表添加，则为 false。

  • • manuallyRemoved

    • boolean

    • 如果 Contact 在 Contact 的列表被分配到 Campaign 时被手动从 Campaign 中移除，则为 true；否则为 false。

  • • listMembership

    • array

    • 此 Contact 属于的与此 Campaign 相关联的 Contact 列表 ID 数组

修改 Campaign 成员关系

请参阅 Campaigns。

获取 Contact 的事件

<?php

$events = $contactApi->getEvents($id, $search, $includeEvents, $excludeEvents, $orderBy, $orderByDir, $page);

Warning

已弃用。请使用 getActivityForContact 代替。

获取 Contact 创建的事件列表。

查询参数

Name	Description
id	Contact ID
filters[search]	用于过滤事件的字符串或搜索命令。
filters[includeEvents][]	要包含的事件类型的数组。
filters[excludeEvents][]	要排除的事件类型的数组。
order	排序规则，格式为 [列名, 排序方向]。
page	要加载的页码

HTTP 请求

GET /contacts/ID/events

Warning

已弃用。请使用 GET /contacts/ID/activity 代替。

响应

Expected response code: 200

{
  "events":[
    {
      "event":"lead.identified",
      "icon":"fa-User",
      "eventType":"Contact identified",
      "eventPriority":-4,
      "timestamp":"2016-06-09T21:39:08+00:00",
      "featured":true
    }
  ],
  "filters":{
    "search":"",
    "includeEvents":[
      "lead.identified"
    ],
    "excludeEvents":[]
  },
  "order":[
    "",
    "ASC"
  ],
  "types":{
    "lead.ipadded":"Accessed from IP",
    "asset.download":"Asset downloaded",
    "campaign.event":"Campaign action triggered",
    "lead.create":"Contact created",
    "lead.identified":"Contact identified",
    "lead.donotcontact":"Do not contact",
    "email.read":"Email read",
    "email.sent":"Email sent",
    "email.failed":"Failed",
    "form.submitted":"Form submitted",
    "page.hit":"Page hit",
    "point.gained":"Point gained",
    "stage.changed":"Stage changed",
    "lead.utmtagsadded":"UTM tags recorded",
    "page.videohit":"Video View Event"
  },
  "total":1,
  "page":1,
  "limit":25,
  "maxPages":1
}

列表属性

名称	类型	描述
events	array	事件列表
event	string	事件类型的 ID
icon	string	来自 FontAwesome 的图标类名
eventType	string	事件的人性化名称
eventPriority	string	事件的优先级
timestamp	timestamp	创建事件的日期和时间
featured	boolean	标志，表示是否为推荐事件
filters	array	查询中使用的过滤器
order	array	查询中使用的排序方式
types	array	可用事件类型的数组
total	int	请求中的事件总数
page	int	当前的 page 编号
limit	int	每个 page 的事件数量限制
maxPages	int	有多少个 pages 的事件

获取特定联系人的活动事件

<?php

$events = $contactApi->getActivityForContact($id, $search, $includeEvents, $excludeEvents, $orderBy, $orderByDir, $page, $dateFrom, $dateTo);

查询参数

名称	描述
id	联系人 ID
filters[search]	用于过滤事件的字符串或搜索命令。
filters[includeEvents][]	要包含的事件类型数组。
filters[excludeEvents][]	要排除的事件类型数组。
filters[dateFrom]	日期范围开始过滤。对于 PHP API 库，必须是 \DateTime 类型，对于 HTTP 参数，格式为 Y-m-d H:i:s。
filters[dateTo]	日期范围结束过滤。对于 PHP API 库，必须是 \DateTime 类型，对于 HTTP 参数，格式为 Y-m-d H:i:s。
order	列和方向的数组 [COLUMN, DIRECTION]。
page	要加载的 page 编号
limit	每个 page 的事件数量限制

获取联系人创建的活动列表。

HTTP 请求

GET /contacts/ID/activity

响应

预期的响应代码: 200

```json {

“events”:[

{

“event”:”lead.identified”, “icon”:”fa-User”, “eventType”:”Contact identified”, “eventPriority”:-4, “timestamp”:”2016-06-09T21:39:08+00:00”, “featured”:true

}

], “filters”:{

“search”:””, “includeEvents”:[

“lead.identified”

], “excludeEvents”:[]

}, “order”:[

“”, “ASC”

], “types”:{

“asset.download”: “Asset downloaded”, “campaign.event”: “Campaign action triggered”, “campaign.event.scheduled”: “Campaign event scheduled”, “lead.donotcontact”: “Do not contact”, “email.failed”: “Email failed”, “email.read”: “Email read”, “email.sent”: “Email sent”, “form.submitted”: “Form submitted”, “lead.imported”: “Imported”, “page.hit”: “Page hit”, “point.gained”: “Point gained”, “stage.changed”: “Stage changed”, “lead.utmtagsadded”: “UTM tags recorded”, “page.videohit”: “Video view event”

}, “total”:1, “page”:1, “limit”:25, “maxPages”:1

}

List Properties

Name	Type	Description
events	array	List of events
event	string	ID of the event type
icon	string	Icon class from FontAwesome
eventType	string	Human name of the event
eventPriority	string	Priority of the event
timestamp	timestamp	Date and time when the event got created
featured	boolean	Flag whether this is a featured event
filters	array	Filters used in the query
order	array	Ordering used in the query
types	array	Array of available event types
total	int	Total number of events in the request
page	int	Current page number
limit	int	Limit of events per page
maxPages	int	How many pages of events are there

Get Activity events for all Contacts

<?php

$events = $contactApi->getActivity($search, $includeEvents, $excludeEvents, $orderBy, $orderByDir, $page, $dateFrom, $dateTo);

Query Parameters

```

• • Name

    • Description

  • • filters[search]

    • 用于过滤事件的字符串或搜索命令。

  • • filters[includeEvents][]

    • 要包含的事件类型数组。

  • • filters[excludeEvents][]

    • 要排除的事件类型数组。

  • • filters[dateFrom]

    • 日期范围起始值。对于 PHP API 库，必须是 \DateTime 类型；对于 HTTP 参数，格式为 Y-m-d H:i:s。

  • • filters[dateTo]

    • 日期范围结束值。对于 PHP API 库，必须是 \DateTime 类型；对于 HTTP 参数，格式为 Y-m-d H:i:s。

  • • order[0]

    • 用于排序的列。可以使用响应中列出的任何列。

  • • order[1]

    • 排序方向：asc 或 desc。

  • • page

    • 要加载的页码。

HTTP 请求

GET /contacts/activity

响应

预期的响应代码: 200

{

“events”: [

{

“event”: “meeting.attended”, “eventId”: “meeting.attended65”, “eventLabel”: “Attended meeting - Mautic instance”, “eventType”: “Meeting attendance”, “timestamp”: “2017-08-03T21:03:04+00:00”, “contactId”: “12180”, “details”: {

“eventName”: “mautic-instance”, “eventId”: “371343405”, “eventDesc”: “Mautic instance”, “joinUrl”: “”

}

}, {

“event”: “webinar.attended”, “eventId”: “webinar.attended67”, “eventLabel”: “Attended webinar - Mautic”, “eventType”: “Webinar attendance”, “timestamp”: “2017-08-03T21:03:04+00:00”, “contactId”: “12180”, “details”: {

“eventName”: “mautic”, “eventId”: “530287395”, “eventDesc”: “Mautic”, “joinUrl”: “”

}

}, {

“event”: “webinar.registered”, “eventId”: “webinar.registered66”, “eventLabel”: “Registered for webinar - Mautic”, “eventType”: “Webinar registered for”, “timestamp”: “2017-08-03T21:03:04+00:00”, “contactId”: “12180”, “details”: {

“eventName”: “mautic”, “eventId”: “530287395”, “eventDesc”: “Mautic”, “joinUrl”: “https://global.gotowebinar.com/join/xxx/xxx”

}

}, {

“event”: “campaign.event”, “eventId”: “campaign.event892”, “eventLabel”: {

“label”: “Contact field value / Campaign Date”, “href”: “/s/campaigns/view/498”

}, “eventType”: “Campaign action triggered”, “timestamp”: “2017-08-03T00:58:25+00:00”, “contactId”: “12281”, “details”: {

“log”: {

“dateTriggered”: “2017-08-03T00:58:25+00:00”, “metadata”: [], “type”: “lead.field_value”, “isScheduled”: “0”, “logId”: “892”, “eventId”: “1457”, “campaignId”: “498”, “eventName”: “Contact field value”, “campaignName”: “Campaign Date”

}

}

}, {

“event”: “email.sent”, “eventId”: “email.sent796”, “eventLabel”: {

“label”: “2017-05-23 - Email - Leads - Nurture Flow (Monica) 1”, “href”: “http://example.com/email/view/597a116ae69ca”, “isExternal”: true

}, “eventType”: “Email sent”, “timestamp”: “2017-07-27T16:14:34+00:00”, “contactId”: “16419”, “details”: {

“stat”: {

“id”: “796”, “dateSent”: “2017-07-27T16:14:34+00:00”, “subject”: “How to make the case for digital”, “isRead”: “0”, “isFailed”: “0”, “viewedInBrowser”: “0”, “retryCount”: “0”, “idHash”: “597a116ae69ca”, “openDetails”: [], “storedSubject”: “How to make the case for digital”, “timeToRead”: false, “emailId”: “78”, “emailName”: “2017-05-23 - Email - Leads - Nurture Flow (Monica) 1”

}, “type”: “sent”

}

}, {

“event”: “email.read”, “eventId”: “email.read769”, “eventLabel”: {

“label”: “Custom Email: device test”, “href”: “http://example.com/email/view/5966b0cd571f4”, “isExternal”: true

}, “eventType”: “Email read”, “timestamp”: “2017-07-12T23:30:56+00:00”, “contactId”: “13930”, “details”: {

“stat”: {

“id”: “769”, “dateRead”: “2017-07-12T23:30:56+00:00”, “dateSent”: “2017-07-12T23:29:17+00:00”, “isRead”: “1”, “isFailed”: “0”, “viewedInBrowser”: “0”, “retryCount”: “0”, “idHash”: “5966b0cd571f4”, “openDetails”: [

{

“datetime”: “2017-07-12 23:30:56”, “Useragent”: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36”, “inBrowser”: false

}, {

“datetime”: “2017-07-13 02:18:51”, “Useragent”: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36”, “inBrowser”: false

}

], “storedSubject”: “device test”, “timeToRead”: “PT1M39S”

}, “type”: “read”

}

}, {

“event”: “lead.ipadded”, “eventId”: “lead.ipadded3263”, “eventLabel”: “127.0.0.1”, “eventType”: “Accessed from IP”, “timestamp”: “2017-07-27T03:09:09+00:00”, “contactId”: “3263”, “details”: []

}, {

“event”: “form.submitted”, “eventId”: “form.submitted503”, “eventLabel”: {

“label”: “3586 Test”, “href”: “/s/forms/view/143”

}, “eventType”: “Form submitted”, “timestamp”: “2017-07-27T03:09:07+00:00”, “contactId”: “16417”, “details”: {

“submission”: {

“id”: 503, “ipAddress”: {

“ip”: “127.0.0.1”

}, “form”: {

“id”: 143, “name”: “3586 Test”, “alias”: “3586_test”

}, “dateSubmitted”: “2017-07-27T03:09:07+00:00”, “referer”: “http://example.com/form/143”, “results”: {

“form_id”: “143”, “email”: “formtest7@example.com”, “f_name”: “”

}

}, “form”: {

“id”: 143, “name”: “3586 Test”, “alias”: “3586_test”

}, “page”: {}

}

}, {

“event”: “page.hit”, “eventLabel”: {

“label”: “Test”, “href”: “/s/pages/view/8”

}, “eventType”: “Page hit”, “timestamp”: “2017-07-21T20:36:49+00:00”, “contactId”: “16380”, “details”: {

“hit”: {

“UserAgent”: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36”, “dateHit”: “2017-07-21T20:36:49+00:00”, “url”: “http://example.com/uncategorized/translation-test1”, “query”: {

“pageUrl”: “http://example.com/uncategorized/translation-test1”

}, “clientInfo”: “a:6:{s:4:"type";s:7:"browser";s:4:"name";s:6:"Chrome";s:10:"short_name";s:2:"CH";s:7:"version";s:4:"59.0";s:6:"engine";s:5:"Blink";s:14:"engine_version";s:0:"";}”, “device”: “desktop”, “deviceOsName”: “Mac”, “deviceBrand”: “”, “deviceModel”: “”, “pageId”: “8”

}

}

}, {

“event”: “point.gained”, “eventLabel”: “2: Page Hit Test / 20”, “eventType”: “Point gained”, “timestamp”: “2017-07-20T22:38:28+00:00”, “contactId”: “16379”, “details”: {

“log”: {

“eventName”: “2: Page Hit Test”, “actionName”: “hit”, “dateAdded”: “2017-07-20T22:38:28+00:00”, “type”: “url”, “delta”: “20”, “id”: “2”

}

}

}, {

“event”: “lead.imported”, “eventId”: “lead.imported6324”, “eventType”: “Imported”, “eventLabel”: {

“label”: “Contact import failed from FakeNameGenerator.com_20d05d9c.csv”, “href”: “/s/contacts/import/view/4”

}, “timestamp”: “2017-07-17T21:42:35+00:00”, “details”: {

“id”: “6324”, “bundle”: “lead”, “object”: “import”, “action”: “failed”, “properties”: {

“line”: 2001, “file”: “FakeNameGenerator.com_20d05d9c.csv”, “error”: “No data found”

}, “UserId”: “2”, “UserName”: “Bob Smith”, “objectId”: “4”, “dateAdded”: “2017-07-17T21:42:35+00:00”

}

}, {

“event”: “asset.download”, “eventId”: “asset.download11”, “eventLabel”: {

“label”: “Download Mautic”, “href”: “/s/assets/view/1”

}, “eventType”: “Asset downloaded”, “timestamp”: “2017-04-04T01:49:13+00:00”, “details”: {

“asset”: {

“id”: 1, “title”: “Download Mautic”, “alias”: “download-mautic”, “description”: “test”

}, “assetDownloadUrl”: “http://example.com/asset/1:download-mautic”

}

},

], “filters”: {

“search”: “”, “includeEvents”: [], “excludeEvents”: []

}, “order”: [

“timestamp”, “DESC”

], “types”: {

“lead.ipadded”: “Accessed from IP”, “asset.download”: “Asset downloaded”, “meeting.attended”: “Attended meeting”, “webinar.attended”: “Attended webinar”, “campaign.event”: “Campaign action triggered”, “campaign.event.scheduled”: “Campaign event scheduled”, “lead.donotcontact”: “Do not contact”, “email.failed”: “Email failed”, “email.read”: “Email read”, “email.sent”: “Email sent”, “form.submitted”: “Form submitted”, “lead.imported”: “Imported”, “page.hit”: “Page hit”, “point.gained”: “Point gained”, “meeting.registered”: “Registered for meeting”, “webinar.registered”: “Registration to Webinar”, “stage.changed”: “Stage changed”, “lead.utmtagsadded”: “UTM tags recorded”, “page.videohit”: “Video view event”

}, “total”: 12, “page”: 1, “limit”: 25, “maxPages”: 1

}

List Properties

Name	Type	Description
events	array	List of events
event	string	ID of the event type
icon	string	Icon class from FontAwesome
eventType	string	Human name of the event
eventPriority	string	Priority of the event
contactId	int	ID of the Contact that created the event
timestamp	timestamp	Date and time when the event got created
featured	boolean	Flag whether this is a featured event
filters	array	Filters used in the query
order	array	Ordering used in the query
types	array	Array of available event types
total	int	Total number of events in the request
page	int	Current page number
limit	int	Limit of events per page
maxPages	int	How many pages of events are there

Get Contact’s Companies

<?php

$companies = $contactApi->getContactCompanies($contactId);

Get a list of Contact’s Companies the Contact belongs to.

HTTP Request

GET /contacts/ID/companies

Response

Expected response code: 200

{
  "total":1,
  "companies":[
    {
      "company_id":"420",
      "date_associated":"2016-12-27 15:03:43",
      "is_primary":"0",
      "companyname":"test",
      "companyemail":"test@example.com",
      "companycity":"Raleigh",
      "score":"0",
      "date_added":"2016-12-27 15:03:42"
    }
  ]
}

List Properties

Name	Type	Description
company_id	int	Company ID
date_associated	datetime	Date and time when the Contact got associated to the Company
date_added	datetime	Date and time when the Company got created
is_primary	boolean	Flag whether the Company association is primary
companyname	string	Name of the Company
companyemail	string	Email of the Company
companycity	string	City of the Company
score	int	Score of the Company

Get Contact’s Devices

<?php

$devices = $contactApi->getContactDevices($contactId);

Get a list of Contact’s devices the Contact has used.

HTTP Request

GET /contacts/ID/devices

Response

Expected response code: 200

```json {

“total”:1, “devices”:[

{

“id”:60, “lead”:[], “clientInfo”:[], “device”:”desktop”, “deviceOsName”:”Ubuntu”, “deviceOsShortName”:”UBT”, “deviceOsPlatform”:”x64”

}

]

}

列表属性

名称	类型	描述
id	int	设备 ID
clientInfo	array	包含有关客户端/浏览器的各种信息的数组
device	string	设备类型；桌面设备、移动设备等。
deviceOsName	string	完整的设备操作系统名称
deviceOsShortName	string	简短的设备操作系统名称
deviceOsPlatform	string	操作系统平台

```