Identify

The Identify endpoint allows you to centralize and standardize your users information in different contexts.

In this guide, we explore various implementation scenarios and practical use cases.

Important

When sending the request from your backend, make sure to include a valid origin in the request header. Don’t forget that this is necessary for request authentication.

Go to the headers section for details.

Websites

Below we share examples of how to implement the Identify endpoint.

Login or registration

Implementing the Identify endpoint during user login or registration on your website allows you to capture their data information.

JavaScript

async function sendIdentifyOnLogin(userData) {
    // You should validate the data before sending it to the endpoint
    // This is a simple example, you should implement a more robust validation
    if (!isValidUserData(userData)) {
        console.error('Invalid user data');
        return;
    }

    try {
        const payload = {
            profile_params: {
                distinct_id: userData.distinct_id,
                first_name: userData.first_name,
                last_name: userData.last_name,
                name: `${userData.first_name} ${userData.last_name}`,
                email: userData.email,
                phone: userData.phone
            },
            product: "web"
        }

        const response = await fetch(process.env.BASE_URL + '/datalake/identify', {
            method: 'POST',
            headers: {
                'Authorization': `${process.env.BEARER_TOKEN}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        // Maybe you want to be more specific about the error splitting by status code.
        // This is just an example.
        if (!response.ok) {
            const errorData = await response.json();
            // Logic to read the error messages from the response and structure them as you need.
            console.error('Your custom message to log the errors');
            return;
        }

        console.log('User identify data sent successfully');
    } catch (error) {
        console.error('Error sending identify request after login:', error);
    }
}

Purchase Completed

When a user completes their purchase, you can capture the information they just provided to update their profile or register it for the first time if you don’t have a login system as in the previous example.

JavaScript

async function sendIdentifyOnPurchase(purchaseData) {
    // Maybe you need to extract the user data from the purchase information that you have.
    // We suggest you to use an auxiliary function to do this.
    const userData = extractUserData(purchaseData);

    // You should validate the data before sending it to the endpoint
    // This is a simple example, you should implement a more robust validation
    if (!isValidUserData(userData)) {
        console.error('Invalid user data');
        return;
    }

    try {
        const payload = {
            profile_params: {
                distinct_id: userData.distinct_id,
                first_name: userData.first_name,
                last_name: userData.last_name,
                name: `${userData.first_name} ${userData.last_name}`,
                email: userData.email,
                phone: userData.phone,
                last_payment_method: purchaseData.payment_method,
                last_payment_amount: purchaseData.amount,
                last_purchase_date: purchaseData.date
            },
            product: "web"
        }

        const response = await fetch(process.env.BASE_URL + '/datalake/identify', {
            method: 'POST',
            headers: {
                'Authorization': `${process.env.BEARER_TOKEN}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        // Maybe you want to be more specific about the error splitting by status code.
        // This is just an example.
        if (!response.ok) {
            const errorData = await response.json();
            // Logic to read the error messages from the response and structure them as you need.
            console.error('Your custom message to log the errors');
            return;
        }

        console.log('User identify data sent successfully');
    } catch (error) {
        console.error('Error sending identify request after login:', error);
    }
}

Ticket Offices

A particular implementation case is for ticket sales systems at ticket offices. This approach allows unifying data from users who purchase at physical points with those who use digital platforms in order to have a single profile for the same user.

Important

For a correct implementation of this case, it is important that you collect customer information, an identifier such as an email or phone number is enough to get started.

Ticket office

JavaScript

async function sendIdentifyFromTicketOffice(customerData, ticketDetails) {
    // You should validate the data before sending it to the endpoint
    // This is a simple example, you should implement a more robust validation
    if (!isValidUserData(customerData)) {
        console.error('Invalid customer data');
        return;
    }

    try {
        const payload = {
            profile_params: {
                distinct_id: ticketDetails.ticketId,
                first_name: customerData.firstName,
                last_name: customerData.lastName,
                name: `${customerData.firstName} ${customerData.lastName}`,
                email: customerData.email || null,
                phone: customerData.phone || null,
                last_purchase_location: ticketDetails.locationName,
                last_payment_method: ticketDetails.paymentMethod,
                last_payment_amount: ticketDetails.amount,
                last_purchase_date: ticketDetails.purchaseDate
            },
            product: "ticket-office"
        }

        const response = await fetch(process.env.BASE_URL + '/datalake/identify', {
            method: 'POST',
            headers: {
                'Authorization': `${process.env.BEARER_TOKEN}`,
                'Origin': 'https://your-pos-system.com',
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        // Maybe you want to be more specific about the error splitting by status code.
        // This is just an example.
        if (!response.ok) {
            const errorData = await response.json();
            // Logic to read the error messages from the response and structure them as you need.
            console.error('Your custom message to log the errors');
            return;
        }

        console.log('Ticket office identify data sent successfully');
    } catch (error) {
        console.error('Error sending identify request after ticket sale:', error);
    }
}

Tip

If you don’t have direct access to your ticket management system’s code or simply want to quickly test the effectiveness of our Identify endpoint, you can opt for a manual process where you save the data in a spreadsheet and later send the information in batches using a script.

We recommend that if the requests cannot be automated from your ticketing systems, you send the batches of information at intervals of up to one hour, ensuring to include appropriate pauses between each request. Include basic information such as name, contact details, and use the value “ticket-office” as the product.

Data Validation

As indicated in other sections, we strongly recommend that you implement validations on the data you send to the Identify endpoint.

In the previous examples, you can see how we invoke a validation function that allows us to stop the process when the data does not meet the expected requirements. Here we share an example of that simple validation on basic fields.

JavaScript

function isValidUserData(userData) {
    if (!userData.first_name || !userData.last_name) {
        console.error('Missing first name or last name in user data: %s', userData);
        return false;
    }

    if (
        userData.email &&
        !/^[^s@]+@[^s@]+.[^s@]+$/.test(userData.email)
    ) {
        console.error('Invalid email format: %s', userData.email);
        return false;
    }

    if (
        userData.phone &&
        !/^+[1-9]d{1,14}$/.test(userData.phone)
    ) {
        console.error('Invalid phone format. Must be in E.164 format: %s', userData.phone);
        return false;
    }

    return true;
}

Conclusion

Proper implementation of the Identify endpoint allows you to centralize and standardize your users’ information across different channels, whether digital or physical. This facilitates comprehensive analysis of your customers’ behavior and enables more informed business decisions.

Tip

If you need specific assistance for your use case or have questions about implementation, don’t hesitate to contact the Reserhub Data Lake team.