Goals and goal values registration

Description

Records a goal achievement and optionally value for a customer profile. As part of event registration, you can also transmit additional profile information.

You can use event data in the following mechanics:

• segment profiles based on activity history;
• trigger a mailing or a scenario;
• add dynamic content into messages.

Request URL

Method: POST

https://example.com/api/v1.1/goals/register

Request parameters

Main parameters

Parameter	Type	Example	Required	Description
token	string	"abcdefghijklmnqrstuvwxyz"	Yes	API token
db_id	int	1	Yes	Database ID
pixel_id	int	1	Yes	Pixel ID
goal	string	"card"	No	Goal name
goals	JSON array	[{"goal": "card", "value": 10.0}]	No	Goals list
value	float	-25.5	No	Goal value
date	string	"2006-01-25T15:04:05+07:00"	No	Event date in RFC 3339 format

Matching parameters

These parameters are used to search for a profile in the database. Read more.

Parameter	Type	Example	Required	Description
matching	string	"email" "email_profile" "phone" "profile_id" "custom"	No, if matched by email	Profile matching mode By default - email
email	string	"john@example.com"	matching:"email"	Email address
phone	string	"+79000000000"	matching:"phone"	Phone number
profile_id	string	"abcdefghijklmnqrstuvwxyz"	matching:"profile_id"	Profile ID
field_name	string	"CRM_ID"	matching:"custom"	Custom profile data field name
field_value	int/string	"123420"	matching:"custom"	Custom profile data field value. Searching by combination of tags is available for tag type profile fields. Values are recorded as a string: "tag-1, tag-2".

Advanced parameters

Parameter	Type	Example	Required	Description
pixel_data	JSON object	{    "key":"value",    "array":[1,2,3] }	No	A JSON object containing additional target event data. The object must not contain nested objects or arrays. The object size is no larger than 1 KB.
skip_triggers	bool	false	No	Disables triggers and scenarios set up for an event. By default — false.
enrich_profile	bool	true	No	The event updates profile data. By default — true.
is_test	bool	false	No	Test event flag. By default — false.
vendor	string	"altcraft"	No	Profile field _vendor at the time of the event
external_type	string	"event_pixel_test"	No	External identifier type
external_event_id	string	"qwerty123"	No	External identifier
altcraft_client_id	string	"9f11d32d-2935-43d0-b8df-f4c3568095b2"	No	Altcraft unique end-to-end identifier

HTTP-parameters

Parameter	Type	Example	Required	Description
referer	string	"api.example.com"	No	Original request referer
user_agent	string	"Mozilla/5.0 (Linux; Android 6.0.1; SM-G935S Build/MMB29K; wv)"	No	Original request browser
accept_language	string	"fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5"	No	Original request language
client_ip	string	"10.0.0.0"	No	Original request IP address
client_ip_v4	string	"198.16.74.224"	No	Client IPv4 address
client_ip_v6	string	"fe80::5215:5556:d75f:806b"	No	Client IPv6 address
browser	string	"Chrome"	No	Client browser You can obtain a list of valid values through the request /v1.1/dictionary ("browsers")
os	string	"Ubuntu"	No	Client operating system You can obtain a list of valid values through the request /v1.1/dictionary ("oses")
device	string	"Desktop"	No	Client device type You can obtain a list of valid values through the request /v1.1/dictionary ("devices")

tip

The browser, os and device fields are automatically populated by the platform based on the contents of the user_agent field.

If you pass both user_agent and separate values for browser, os and device in the same request, the data from user_agent takes precedence and overwrites the specified values.

If you pass browser, os and device fields without user_agent, you must specify "enrich_profile": true to update the profile, otherwise the platform will not update the profile.

Geolocation parameters

The platform will automatically determine the values if client_ip is passed.

Parameter	Type	Example	Required	Description
lat	float	55.244075	Yes, if lon is passed	Client latitude
lon	float	55.244075	Yes, if lat is passed	Client longitude
country	string	"RU"	No	Client country (ISO code or full name)
region	string	"Ryazan"	No	Client region
city	string	"Ryazan"	No	Client city
address	string	"Pochtovaya street"	No	Client address
zip	string	"390000"	No	Client zip code
time_zone	string	"Europe/Moscow"	No	Client timezone

tip

The platform automatically determines the values of the country, region, city, zip, and time_zone fields based on the IP address passed in the client_ip, client_ip_v4, or client_ip_v6 parameters. If both the IP address and individual values for these fields are specified in the request, the IP-defined data will take precedence and overwrite the manually passed values.

To update a profile using values from the country, region, city, zip and time_zone fields, the "enrich_profile": true parameter must be set.

UTM-parameters

Parameter	Type	Example	Required	Description
utm_content	string	"utm_content"	No	UTM params
utm_medium	string	"utm_medium"	No
utm_source	string	"utm_source"	No
utm_campaign	string	"utm_campaign"	No
utm_term	string	"utm_term"	No

Network parameters

Parameter	Type	Example	Required	Description
net_ssid	string	"10.200.0.0"	No	Client network name
net_mac_addr	string	"28:87:ba:c1:0d:5e"	No	Client MAC address
net_gateway_ipv4	string	"10.200.0.1"	No	Client gateway IPv4 address
net_gateway_ipv6	string	"::ff"	No	Client gateway IPv6 address

Mailing parameters

Parameter	Type	Example	Required	Description
send_message_id	string	"w4Wq877djSG1_2_a1_6t_2p_U_2_g. 2UCSmxz7zFnuCfCMK_5KmKH9"	No	ID of the sent message in the platform. Use the parameter to allow you to associate a pixel event with a specific mailing.

Loyalty programs parameters

Parameter	Type	Example	Required	Description
loyalty_id	int	5	No	Loyalty program ID
promo_id	string	"6285183c3f62fcd4ac5ed36d"	No	Attached promo code ID

Market parameters

Parameter	Type	Example	Required	Description
endpoint_eid	string	"example_endpoint"	No	External contact point identifier. If a specific profile base is selected for a pixel, then this base must match the sales channel base.
order_eid	string	"12345"	No	External order ID
product_eid	string	"example_product"	Yes, if sku_eid is passed	External product ID
sku_eid	string	"example_sku"	No	External SKU ID. When this parameter is used, product_eid must also be passed in the request.
region_eid	string	"region_eYFe2AE6s"	No	External region ID
count_items	int	1	No	Quantity of items in the order item
categories	array	[    "category_1",    "category_2" ]	No	Product categories or SKUs

info

The maximum length of any string field is 128 characters.

Request examples

1 goal, no original request header data used:

JSON

{
    "token": "abcdefghijklmnqrstuvwxyz",
    "db_id": 1,
    "goal": "card",
    "pixel_id": 1,
    "referer": "api.example.com",
    "value": -25.5,
    "matching": "profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz"
}

XML

<xml>
    <token>2fefb577533d4cae919350c450755239</token>
    <db_id>1</db_id>
    <goal>card</goal>
    <pixel_id>1</pixel_id>
    <referer>api.example.com</referer>
    <value>-25.5</value>
    <matching>profile_id</matching>
    <profile_id>65d49bc74a6f1407ac656547</profile_id> 
</xml>

2 goals, IP and referer from the original request head are used:

JSON

{
    "token": "91f1dfa81c264a938b475677c60ce967",
    "client_ip": "10.20.30.40",
    "db_id": 24,
    "goals": [
        {
            "goal": "cart",
            "value": 10.99
        },
        {
            "goal": "two",
            "value": -12.34
        }
    ],
    "pixel_id": 7,
    "matching": "profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz",
    "referer": "api.req.from.my.site"
}

XML

<xml>
    <token>abcdefghijklmnqrstuvwxyz</token>
    <client_ip>10.20.30.40</client_ip>
    <db_id>24</db_id>
    <goals>
        <goal>cart</goal>
        <value>10.99</value>
    </goals>
    <goals>
        <goal>two</goal>
        <value>-12.34</value>
    </goals>
    <pixel_id>7</pixel_id>
    <matching>profile_id</matching>
    <profile_id>abcdefghijklmnqrstuvwxyz</profile_id>
    <referer>api.req.from.my.site</referer>
</xml>

Example of a request to send additional information about an event:

JSON

{
    "token": "abcdefghijklmnqrstuvwxyz",
    "db_id": 24,
    "goals": [
        {
            "goal": "cart",
            "value": 10.99
        },
        {
            "goal": "two",
            "value": -12.34
        }
    ],
    "client_ip": "192.168.0.0",
    "pixel_id": 7,
    "referer": "api.req.from.my.site",
    "accept_language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
    "matching": "profile_id",
    "profile_id": "651516181a5c52f94532fb1d",
    "pixel_data": {
        "hello": "hi",
        "arr": [
            1,
            2,
            3
        ],
        "int_val": 56893,
        "bool_val": true,
        "date_val": "2023-08-12"
    },
    "skip_triggers": false,
    "enrich_profile": true,
    "is_test": true,
    "vendor": "altcraft",
    "external_type": "event_pixel_test",
    "external_event_id": "qwerty123",
    "altcraft_client_id": "9f11d32d-2935-43d0-b8df-f4c3568095b2",
    "browser": "Chrome",
    "os": "Ubuntu",
    "device": "Desktop",
    "utm_content": "utm_content",
    "utm_medium": "utm_medium",
    "utm_source": "utm_source",
    "utm_campaign": "utm_campaign",
    "utm_term": "utm_term",
    "client_ip_v4": "198.16.74.224",
    "client_ip_v6": "fe80::5215:5556:d75f:806b",
    "net_ssid": "10.200.0.0",
    "net_mac_addr": "28:87:ba:c1:0d:5e",
    "net_gateway_ipv4": "10.200.0.1",
    "net_gateway_ipv6": "::ff",
    "loyalty_id": 5,
    "promo_id": "6285183c3f62fcd4ac5ed36d",
    "endpoint_eid": "online_store",
    "order_eid": "12345",
    "product_eid": "hd_450_bt_earphones",
    "sku_eid": "hd_450bt_earphones_black",
    "region_eid": "region_eYFe2AE6s",
    "count_items": 1,
    "categories": [
        "category_KBZ1qurFP"
    ],
    "lat": 55.244075,
    "lon": 19.379932,
    "country": "RU",
    "region": "Ryazan",
    "city": "Ryazan",
    "address": "Pochtovaya street",
    "zip": "390000",
    "time_zone": "Europe/Moscow",
    "send_message_id": "w4Wq877djSG1_2_a1_6t_2p_U_2_g.2UCSmxz7zFnuCfCMK_5KmKH9"
}

XML

<xml>
    <token>abcdefghijklmnqrstuvwxyz</token>
    <db_id>24</db_id>
    <goals>
        <goal>cart</goal>
        <value>10.99</value>
    </goals>
    <goals>
        <goal>two</goal>
        <value>-12.34</value>
    </goals>
    <client_ip>192.168.0.0</client_ip>
    <pixel_id>7</pixel_id>
    <referer>api.req.from.my.site</referer>
    <accept_language>fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5</accept_language>
    <user_agent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36</user_agent>
    <matching>profile_id</matching>
    <profile_id>651516181a5c52f94532fb1d</profile_id>
    <pixel_data>
        <hello>hi</hello>
        <arr>1</arr>
        <arr>2</arr>
        <arr>3</arr>
        <int_val>56893</int_val>
        <bool_val>true</bool_val>
        <date_val>2023-08-12</date_val>
    </pixel_data>
    <skip_triggers>false</skip_triggers>
    <enrich_profile>true</enrich_profile>
    <is_test>true</is_test>
    <vendor>altcraft</vendor>
    <external_type>event_pixel_test</external_type>
    <external_event_id>qwerty123</external_event_id>
    <altcraft_client_id>9f11d32d-2935-43d0-b8df-f4c3568095b2</altcraft_client_id>
    <browser>Chrome</browser>
    <os>Ubuntu</os>
    <device>Desktop</device>
    <utm_content>utm_content</utm_content>
    <utm_medium>utm_medium</utm_medium>
    <utm_source>utm_source</utm_source>
    <utm_campaign>utm_campaign</utm_campaign>
    <utm_term>utm_term</utm_term>
    <client_ip_v4>198.16.74.224</client_ip_v4>
    <client_ip_v6>fe80::5215:5556:d75f:806b</client_ip_v6>
    <net_ssid>10.200.0.0</net_ssid>
    <net_mac_addr>28:87:ba:c1:0d:5e</net_mac_addr>
    <net_gateway_ipv4>10.200.0.1</net_gateway_ipv4>
    <net_gateway_ipv6>::ff</net_gateway_ipv6>
    <loyalty_id>5</loyalty_id>
    <promo_id>6285183c3f62fcd4ac5ed36d</promo_id>
    <endpoint_eid>online_store</endpoint_eid>
    <order_eid>12345</order_eid>
    <product_eid>hd_450_bt_earphones</product_eid>
    <sku_eid>hd_450bt_earphones_black</sku_eid>
    <region_eid>region_eYFe2AE6s</region_eid>
    <count_items>1</count_items>
    <categories>category_KBZ1qurFP</categories>
    <lat>55.244075</lat>
    <lon>19.379932</lon>
    <country>RU</country>
    <region>Ryazan</region>
    <city>Ryazan</city>
    <address>Pochtovaya street</address>
    <zip>390000</zip>
    <time_zone>Europe/Moscow</time_zone>
    <send_message_id>w4Wq877djSG1_2_a1_6t_2p_U_2_g.2UCSmxz7zFnuCfCMK_5KmKH9</send_message_id>
</xml>

Response example

JSON

{
    "error": 0,
    "error_text": "Successful operation"
}

XML

<xml>
    <error>0</error>
    <error_text>Successful operation</error_text>
</xml>

Response parameters

Parameter	Type	Description
error	int	Error code
error_text	string	Error text