Skip to main content

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.

Request URL​

Method: POST

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

Request parameters​

Main parameters​

ParameterTypeExampleRequiredDescription
tokenstring"abcdefghijklmnqrstuvwxyz"YesAPI token
db_idint1YesDatabase ID
pixel_idint1YesPixel ID
goalstring"card"NoGoal name
goalsJSON array
[{"goal": "card", "value": 10.0}]
NoGoals list
valuefloat-25.5NoGoal value
datestring"2006-01-25T15:04:05+07:00"NoEvent date in RFC 3339 format

Matching parameters​

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

ParameterTypeExampleRequiredDescription
matchingstring

"email"
"email_profile"
"phone"
"profile_id"
"custom"

No, if matched by emailProfile matching mode
By default - email
emailstring"john@example.com"matching:"email"Email address
phonestring"+79000000000"matching:"phone"Phone number
profile_idstring"abcdefghijklmnqrstuvwxyz"matching:"profile_id"Profile ID
field_namestring"CRM_ID"matching:"custom"Custom profile data field name
field_valueint/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​

ParameterTypeExampleRequiredDescription
pixel_dataJSON object
{
   "key":"value",
   "array":[1,2,3]
}
NoA 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_triggersboolfalseNoDisables triggers and scenarios set up for an event.

By default — false.
enrich_profilebooltrueNoThe event updates profile data.

By default — true.
is_testboolfalseNoTest event flag.

By default — false.
vendorstring"altcraft"NoProfile field _vendor at the time of the event
external_typestring"event_pixel_test"NoExternal identifier type
external_event_idstring"qwerty123"NoExternal identifier
altcraft_client_idstring"9f11d32d-2935-43d0-b8df-f4c3568095b2"NoAltcraft unique end-to-end identifier

HTTP-parameters​

ParameterTypeExampleRequiredDescription
refererstring"api.example.com"NoOriginal request referer
user_agentstring"Mozilla/5.0 (Linux; Android 6.0.1; SM-G935S Build/MMB29K; wv)"NoOriginal request browser
accept_languagestring"fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5"NoOriginal request language
client_ipstring"10.0.0.0"NoOriginal request IP address
client_ip_v4string"198.16.74.224"NoClient IPv4 address
client_ip_v6string"fe80::5215:5556:d75f:806b"NoClient IPv6 address
browserstring"Chrome"NoClient browser

You can obtain a list of valid values through the request /v1.1/dictionary ("browsers")
osstring"Ubuntu"NoClient operating system

You can obtain a list of valid values through the request /v1.1/dictionary ("oses")
devicestring"Desktop"NoClient 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.

ParameterTypeExampleRequiredDescription
latfloat55.244075Yes,
if lon is passed		Client latitude
lonfloat55.244075Yes,
if lat is passed		Client longitude
countrystring"RU"NoClient country (ISO code or full name)
regionstring"Ryazan"NoClient region
citystring"Ryazan"NoClient city
addressstring"Pochtovaya street"NoClient address
zipstring"390000"NoClient zip code
time_zonestring"Europe/Moscow"NoClient 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​

ParameterTypeExampleRequiredDescription
utm_contentstring"utm_content"NoUTM params
utm_mediumstring"utm_medium"No
utm_sourcestring"utm_source"No
utm_campaignstring"utm_campaign"No
utm_termstring"utm_term"No

Network parameters​

ParameterTypeExampleRequiredDescription
net_ssidstring"10.200.0.0"NoClient network name
net_mac_addrstring"28:87:ba:c1:0d:5e"NoClient MAC address
net_gateway_ipv4string"10.200.0.1"NoClient gateway IPv4 address
net_gateway_ipv6string"::ff"NoClient gateway IPv6 address

Campaign parameters​

ParameterTypeExampleRequiredDescription
send_message_idstring"w4Wq877djSG1_2_a1_6t_2p_U_2_g.
2UCSmxz7zFnuCfCMK_5KmKH9"		NoID of the sent message in the platform. Use the parameter to allow you to associate a pixel event with a specific campaign.

Loyalty programs parameters​

ParameterTypeExampleRequiredDescription
loyalty_idint5NoLoyalty program ID
promo_idstring"6285183c3f62fcd4ac5ed36d"NoAttached promo code ID

Market parameters​

ParameterTypeExampleRequiredDescription
endpoint_eidstring"example_endpoint"NoExternal contact point identifier.

If a specific profile base is selected for a pixel, then this base must match the sales channel base.
order_eidstring"12345"NoExternal order ID
product_eidstring"example_product"Yes,
if sku_eid is passed		External product ID
sku_eidstring"example_sku"NoExternal SKU ID. When this parameter is used, product_eid must also be passed in the request.
region_eidstring"region_eYFe2AE6s"NoExternal region ID
count_itemsint1NoQuantity of items in the order item
categoriesarray
[
   "category_1",
   "category_2"
]
NoProduct categories or SKUs
info

The maximum length of any string field is 128 characters.

Request examples​

1 goal, no original request header data used:

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

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

{
    "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"
}

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

{
    "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"
}

Response example​

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

Response parameters​

ParameterTypeDescription
errorintError code
error_textstringError text
Last updated on