Sending form data with API

Form data is usually tracked by using the SDK, but you can make API calls from your backend, so that you have more control over the process and access to detailed event logs. Unlike the SDK, the logic of calling endpoints can also be modified according to business requirements.

WARNING: The API calls must be made by the server!
Making API calls from the browser exposes your API key.

The logic described in this article will let you detect if the customer who fills in a form (for example, a log-in form) is the same as the one currently recognized in the browser.

The data is saved in a form.submit event. The event contains all data from the form.

Note: If you implement tracking form data over the API, it is recommended to block sending form.submit events by the SDK. See Event authentication settings.

To learn more about our API, see these articles.

Implementation overview

The flowchart presents an overview of the logic which replicates the behavior of tracking form data over the SDK.

In certain conditions, some steps of the logic are redundant. Thanks to this, all scenarios are covered with inserting additional checks.

WARNING: Depending on your configuration, the unique identifier is email (default setting) or custom ID (see Setting non-unique emails.)
Note: This logic is a suggestion. You can modify it according to your business needs or create your own. Remember to cover all the scenarios.
Sending form data with API
Overview of tracking form data by using the API

Implementation details

This section explains in detail the flow of events and actions, and how to implement them.

Customer enters site and fills in HTML form

HTML form example:

<form action="" method="post">
    <input type="text" name="email" placeholder="Email" value="john.doe@synerise.com" />
    <input type="text" name="name" placeholder="Name" value="John" />
    <input type="text" name="surname" placeholder="Surname" value="Doe" />
    <input type="submit" value="Save" />
</form>
  1. Gather data from the HTML form.
  2. Optional: Validate the data in the form (for example, check if email is properly formatted).
  3. Optional: Authenticate the customer.
  4. Check if the _snrs_p cookie has a value for identityHash.
    _snrs_p cookie example: 
    _snrs_p:
    host:
    permUuid:e0097757-d1e2-44ac-ba3c-d97979a354c1 # deprecated
    uuid:e0097757-d1e2-44ac-ba3c-d97979a354c1 # current UUID
    identityHash:277163923
    init:1613135695
    last:1625149870.406
    current:1625149875
    uniqueVisits:7
    allVisits:17
  5. Perform one of the following actions:

If identityHash does not a have a value

The customer is currently anonymous. The data from the anonymous account needs to be associated with the data for the customer who filled in the HTML form.

  1. Generate an UUIDv5 for the customer. For details, see this article.

  2. Send a create/update API call to merge the anonymous customer with the one who was identified in the HTML form.
    The request body must contain an array with two objects: one with the identifier and the new UUIDv5, the other with the identifier and the UUID from the _snrs_p cookie.
    API reference is available here.
    If you want to send additional data, such as agreements or free-form attributes, they must be included in the object with the new UUIDv5.

    See curl example (email)

    The highlighted properties are required, the others are optional. For a comprehensive list of properties you can send, see API reference.

    curl --location --request POST '{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...yeIc' \
--data-raw '[
    {
        "email": "example@synerise.com",
        "uuid": "4f82f7a9-0745-55a3-b028-e301b19bf8ec",
        "agreements": {
            "email": true,
            "sms": true
        },
        "tags": [
            "exampleTag"
        ],
        "attributes": {
            "customAttribute1": true,
            "customAttribute2": "string",
            "customAttribute3": 42
        }
    },
    {
        "email": "example@synerise.com",
        "uuid": "35a1c1d8-2468-4c47-9be2-f2c2edf9f526"
    }
]'

    See curl example (customId)

    The highlighted properties are required, the others are optional. For a comprehensive list of properties you can send, see API reference.

    curl --location --request POST '{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...yeIc' \
--data-raw '[
    {
        "customId": "example.customId",
        "uuid": "d2bdec3a-96d9-5805-9ca2-1557aec691b1",
        "agreements": {
            "email": true,
            "sms": true
        },
        "tags": [
            "exampleTag"
        ],
        "attributes": {
            "customAttribute1": true,
            "customAttribute2": "string",
            "customAttribute3": 42
        }
    },
    {
        "customId": "example.customId",
        "uuid": "35a1c1d8-2468-4c47-9be2-f2c2edf9f526"
    }
]'

  3. Send a form.submit event. The data from the form is stored in the params object.
    API reference is available here.

    See curl example (email)

    curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer eyJh...T-hyeIc' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "label": "Customer submitted a form",
    "action": "form.submit",
    "client": {
        "email": "example@synerise.com"
    },
    "params": {
        "firstname": "John",
        "lastname": "Doe",
        "formType": "exampleFormType"
    }
}'

    See curl example (customId)

    curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer eyJh...T-hyeIc' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "label": "Customer submitted a form",
    "action": "form.submit",
    "client": {
        "customId": "example@synerise.com"
    },
    "params": {
        "firstname": "John",
        "lastname": "Doe",
        "formType": "exampleFormType"
    }
}'

  4. Store the new UUIDv5 in the browser in one of the following ways:

    • If after SDK initialization: use the SR.client.setUuid("new_uuid"); method; replace new_uuid with the UUID. The UUID is written to the _snrs_p cookie immediately.
    • If the Synerise SDK is not initialized, store the UUID in the _snrs_reset_uuid cookie. The UUID is written to the _snrs_p at SDK initialization.

Result: The customer’s data is saved, a recognized profile is created.

If identityHash has a value

The customer is recognized. You need to check if the customer who filled in the HTML form is the same as the one whose data is currently saved in the _snrs_p cookie.

  1. Generate the identityHash of the customer who filled in the form in one of the following ways:

    • If Synerise SDK is initialized, use the following function:

      SR.client.hashIdentity("unique_id")

      where unique_id is the email or custom ID

    • If Synerise SDK is not initialized, use the following JS code or your own version of it, which can be written in another language: 

      // arguments
// data: string (email or customId) to create hash from

// returned value
// hash: hashed string

hashString: function (data) {
    var hash = 0;
    if (data.length === 0) {
        return hash;
    }
    for (var i = 0; i < data.length; i++) {
        var char = data.charCodeAt(i);
        hash = ((hash << 5) - hash) + char;
        hash = hash & hash;
    }
    return hash;
}

  2. Compare the generated hash with identityHash from the _snrs_p cookie:

If identityHash is identical

The customer who filled the form is the same as the one who visited the site previously. You can send their data.

  1. Send a form.submit event. The data from the form is stored in the params object.
    API reference is available here.
    See curl example (email)

    curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer eyJh...T-hyeIc' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "label": "Customer submitted a form",
    "action": "form.submit",
    "client": {
        "email": "example@synerise.com"
    },
    "params": {
        "firstname": "John",
        "lastname": "Doe",
        "formType": "exampleFormType"
    }
}'

    See curl example (customId)

    curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer eyJh...T-hyeIc' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "label": "Customer submitted a form",
    "action": "form.submit",
    "client": {
        "customId": "example@synerise.com"
    },
    "params": {
        "firstname": "John",
        "lastname": "Doe",
        "formType": "exampleFormType"
    }
}'

Result: The data from the form is saved to the customer’s account.

If identityHash is not identical

The customer who filled the form is not the same who visited the site previously.

  1. Generate an UUIDv5 for the customer. For details, see this article.

  2. Send a create/update API call to create/update the profile which is the new context with the UUIDv5.
    The request body is a single-object array. The object contains the new UUIDv5 and the unique identifier. If the profile already has this UUIDv5, sending the same data again does not cause any problems. You do not need to check before sending the call.
    API reference is available here.

    See curl example (email)

    The highlighted properties are required, the others are optional. For a comprehensive list of properties you can send, see API reference.

    curl --location --request POST '{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...yeIc' \
--data-raw '[
    {
        "email": "example@synerise.com",
        "uuid": "4f82f7a9-0745-55a3-b028-e301b19bf8ec",
        "agreements": {
            "email": true,
            "sms": true
        },
        "tags": [
            "exampleTag"
        ],
        "attributes": {
            "customAttribute1": true,
            "customAttribute2": "string",
            "customAttribute3": 42
        }
    }
]'

    See curl example (customId)

    The highlighted properties are required, the others are optional. For a comprehensive list of properties you can send, see API reference.

    curl --location --request POST '{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...yeIc' \
--data-raw '[
    {
        "customId": "example.customId",
        "uuid": "d2bdec3a-96d9-5805-9ca2-1557aec691b1",
        "agreements": {
            "email": true,
            "sms": true
        },
        "tags": [
            "exampleTag"
        ],
        "attributes": {
            "customAttribute1": true,
            "customAttribute2": "string",
            "customAttribute3": 42
        }
    }
]'

    Result: The profile is created/updated with the new UUIDv5 and the additional data you sent. The UUIDv5 is always the same for a given customer, regardless of where and how it was generated.

  3. Send a form.submit event. The data from the form is stored in the params object.
    API reference is available here.

    See curl example (email)

    curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer eyJh...T-hyeIc' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "label": "Customer submitted a form",
    "action": "form.submit",
    "client": {
        "email": "example@synerise.com"
    },
    "params": {
        "firstname": "John",
        "lastname": "Doe",
        "formType": "exampleFormType"
    }
}'

    See curl example (customId)

    curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/events/custom' \
--header 'Authorization: Bearer eyJh...T-hyeIc' \
--header 'Api-Version: 4.4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "label": "Customer submitted a form",
    "action": "form.submit",
    "client": {
        "customId": "example@synerise.com"
    },
    "params": {
        "firstname": "John",
        "lastname": "Doe",
        "formType": "exampleFormType"
    }
}'

  4. Store the new UUIDv5 in the browser in one of the following ways:

    • If after SDK initialization: use the SR.client.setUuid("new_uuid"); method; replace new_uuid with the UUID. The UUID is written to the _snrs_p cookie immediately.
    • If the Synerise SDK is not initialized, store the UUID in the _snrs_reset_uuid cookie. The UUID is written to the _snrs_p at SDK initialization.

    Result: The customer context in the browser changes to the customer with the new UUIDv5.

Marketing agreements

See Newsletter agreements.

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker