Set Channel Identifiers
A channel identifier is the identifier value on a reach channel and can be used as the target of that channel. Both setting and unbinding are performed by EUID and channel ID.
The full endpoint URL is the data center Base URL plus the API path below. See REST API Overview for how to obtain the Base URL, API Key, and API Secret.
Invocation Verification
The EngageLab REST API uses HTTP Basic Authentication as the verification method. Add Authorization to the HTTP Header:
Authorization: Basic ${base64_auth_string}
The base64_auth_string is generated using the following algorithm: base64(api_key:api_secret).
- The header name is "Authorization", and the value is the base64-encoded "username:password" pair (separated by a colon).
- For the MA API, the username corresponds to the APIKey, and the password corresponds to the APISecret. Please configure an API-type data source to obtain the APIKey and API Secret.
Set Channel Identifiers
Invocation Address
POST /v1/user/channel
Request Example
Request Header
> POST /v1/user/channel
> Content-Type: application/json
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
Request Body
{
"euid": 10362473,
"channel_id": 8801,
"ma_rid": "1a0018970d1c9f8f8e2",
"value": [
"channel_identifier_1",
"channel_identifier_2"
]
}
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
euid |
Long | Yes | Unique user ID. The user must already exist in the current project. |
channel_id |
Long | Yes | Reach channel ID. The channel must already exist in the current project. |
ma_rid |
String | No | MA Registration ID. When provided, the channel identifiers written by this request are bound to this MA RID and the platform is recorded. If this MA RID is later transferred to another EUID, the channel identifiers bound to it are transferred with it. When the field is omitted, an empty string, or whitespace only, this write creates no binding; an existing binding on the identifiers written by this request is cleared. If a platform cannot be parsed from the value, the set request fails. |
value |
Array<String> | Yes | Channel identifier values to set. The list cannot be empty, and each item must not be blank. Values are stored as given: matching is case-sensitive, and leading or trailing spaces are not trimmed. Duplicate values in the same request are deduplicated. |
For the same euid + channel_id, the same identifier is rewritten from this request: the old record is removed and a new record is written, with the update time set to the current time. Identifiers already stored but absent from this list are left unchanged. A new value is appended.
For AppPush/WebPush channels, the same channel identifier under the same channel_id can belong to only one EUID. After the value is written to the new EUID, the system removes it from every other EUID that still has it. Other channel types do not use this uniqueness rebinding.
Return Parameters
| Field | Type | Required | Description |
|---|---|---|---|
code |
Int | Yes | Whether the API call succeeded. 0 means success. |
message |
String | Yes | Result description of the API call. |
Success Example
{
"code": 0,
"message": "success"
}
Unbind Channel Identifiers
Invocation Address
POST /v1/user/channel/unbind
Request Example
Request Header
> POST /v1/user/channel/unbind
> Content-Type: application/json
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
Request Body
{
"euid": 10362473,
"channel_id": 8801,
"value": [
"channel_identifier_1",
"channel_identifier_2"
]
}
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
euid |
Long | Yes | Unique user ID. |
channel_id |
Long | Yes | Reach channel ID. |
value |
Array<String> | Yes | Channel identifier values to unbind. Each value must exactly match a stored identifier. Matching is case-sensitive, and leading or trailing spaces are not trimmed. |
Unbind matches channel identifier values, not ma_rid. The unbind request has no ma_rid field. The API removes records that exactly match euid + channel_id + value. If the user does not exist, or the user has no exactly matching identifier, no data is changed and the API still returns success. Unbind does not check whether channel_id belongs to the current project.
Return Parameters
| Field | Type | Required | Description |
|---|---|---|---|
code |
Int | Yes | Whether the API call succeeded. 0 means success. |
message |
String | Yes | Result description of the API call. |
Success Example
{
"code": 0,
"message": "success"
}
Error Codes
When business validation fails, the set API returns the following error codes with HTTP status 400. The message field in the response body is the English explanation, not the description in the table below. The unbind API returns 55004 only when a required field is invalid or the request body cannot be parsed. If the user does not exist or the identifier does not exist, unbind still returns success.
| Code | Description | Detail |
|---|---|---|
| 55004 | Invalid business parameter | On set, if channel_id does not exist in the current project, message is channel_id does not exist in current project: {channel_id}. On set, if ma_rid cannot be parsed into a platform, message is ma_rid is invalid. On set and unbind, a missing required field, an empty value, a blank item, or a request body that cannot be parsed (message is Invalid request payload format) also returns this code. |
| 55108 | Invalid EUID | Returned only by the set API. The EUID does not exist in the current project. message is EUID does not exist: {euid}. |
Failure Examples
channel_id does not exist:
{
"code": 55004,
"message": "channel_id does not exist in current project: 8801"
}
ma_rid cannot be parsed:
{
"code": 55004,
"message": "ma_rid is invalid"
}
The EUID does not exist:
{
"code": 55108,
"message": "EUID does not exist: 10362473"
}
