In this tutorial, we explain how to configure real-time validation via Web service, both during the identification process (Login) and for additional fields in the registration form.

The tutorial covers the following topics:

1. Introduction

2. Initial requirements

3. Promotion configuration

4. Web service technical configuration

1. Introduction

Easypromos allows you to validate user data in real time during the identification and registration process of a promotion by checking it against an external system through an API or Web service connection.

This functionality allows you to verify that users meet specific requirements to participate in a promotion by querying an external database managed by the client, such as a newsletter subscriber database, a contact CRM, or a customer loyalty program database.

Real-time validation is available at two stages of the participation process:

• During the identification process (Login): allows you to validate the email addresses or customer codes entered by users.
• During the registration process: allows you to validate the information entered in the additional text fields of the registration form.

This way, you can check both whether a user is authorized to access the promotion and whether the information they provide during registration meets the organizer's requirements.

Use cases:

1. Running a prize draw among newsletter subscribers: When users try to log in to participate, the system will check in real time whether their email address is included in the subscriber database. If it is not, they will see an error message with a link to sign up for the newsletter.
2. Creating a prize wheel game for loyalty program customers: Users must enter their customer number to log in and participate. The system will check in real time whether the number entered exists in the customer database.
3. Validating additional information during registration: You can ask users to enter specific information in a text field on the registration form, such as a membership number, employee code, or customer ID. The system will check in real time whether the information entered is valid according to the external database.

Note: This functionality applies when the identification and registration process happens within Easypromos, meaning users must complete the promotion registration form. If you are looking for a Single Sign-On (SSO) solution, where the user is authenticated directly in your system, you should use the Autologin API or the integration with Open ID Connect.

2. Initial Requirements

These are the requirements that the person managing the promotion, who does not necessarily have to be the developer, must meet and verify.

General Requirements

• The client must have an API or Webservice that allows Easypromos to send the email entered by the user and respond in real time. Please refer to the "developers" section for the technical specifications the webservice must meet.
• A White Label or Corporate plan is required. This is not included in Premium or Basic plans.
• The promotion version must be White Label. It does not apply to Premium promotions.

Requirements for validating data during Login

• The identification/Login screen must be enabled. It does not apply when the one-step login and registration system is activated.
• This feature only applies to the following login methods:
  • Email (if you are validating email addresses)
  • Customer code (if you are validating customer numbers)

Requirements for validating registration form data

One or more additional text fields must be included in the registration form. These are the fields where Web service validation will be configured.

3. Promotion Configuration

Once these requirements are met, for Login validation, the identification and registration screen must be configured as follows:

1. Access the Promotion Editor
2. Go to Pages > Login and Registration > Login Tab
3. Ensure that the option "One-step identification and registration process" is disabled.
4. Enable Login with Email and, in its options, enable Email Restrictions "Via external API (Web service)". If instead of validating emails, you want to validate customer codes, you should enable the "Login with customer code" option.
5. The Method, Content-type, Headers, and Web service URL must be provided by the integration developer. This is explained in the next section of the tutorial.
6. Error message: Enter the text a user will see in case of a validation error. Take advantage of this by including a link to your system for registration. Example: "The email is not valid. If you are not yet a subscriber, sign up here."

For registration form field validation, follow the steps below:

1. Access the Promotion Editor.
2. Go to Pages > Login and Registration > Registration tab.
3. Add a new field of the Additional text field type.
4. In the field configuration options, enable Validation method > Via external API (Web service).
5. The Method, Content-Type, Headers, and Web service URL must be provided by the integration developer. These settings are explained in the next section of this tutorial.

4. Web service technical configuration

This section of the tutorial is specifically aimed at developers or technical integrators responsible for setting up the connection with the external web service. You will need to handle the configuration of the API, including headers, methods, and the web service URL, to enable real-time validation.

Currently, calls to URLs via HTTPS using the GET method are supported, expecting a JSON response type .

The URL must respond with a 200 code if the email has access to the promotion. If any other code is received, it will be interpreted that the user does not have access to the promotion. 

Since this is a real-time check, each time the user enters the code, a call to the web service is made. This call has a 2-second timeout. Therefore, the implementation of the web service must be able to return the 200 code in less than two seconds to avoid negatively impacting the user experience; otherwise, the validation will fail.

Headers

Configure the headers of the request with the authentication requirements of your web service.

Header configuration is especially important as it allows the client's URL to be protected with private tokens and prevents the API from being accessed through potential brute force attacks. Requests to the API are made server-to-server, so these tokens will never be visible from the user's browser.

Web service URL

The service URL must point to the endpoint programmed by the client. This endpoint requires that the variable {EMAIL} be added to the URL itself or as a GET parameter. This variable will be replaced by the email entered by the user.

Examples of valid URLs to check the email:

If instead of validating emails, you are validating customer codes, you should use the {CUSTOMER_NUMBER} parameter.

Source IP address for validation requests

Easypromos sends validation requests to your web service from the IP address 34.156.157.35. If your server restricts incoming connections using a firewall or an IP allowlist, add this address so it can receive requests from Easypromos.

Allowlisting this IP does not replace authenticating requests using the headers configured for your web service.

Testing

You can use the [Run a test] function to try different emails and see the response. For each email entered, the response from the web service is shown in the test pop-up screen, for example:

To test this function before programming the final URL, we have created two test URLs: one that always responds with a code 200, accepting the email, and another that returns a code 404, rejecting any email.

These URLs are:

- https://wl.easypromosapp.com/v24/ok/{EMAIL} - To test the OK answer

- https://wl.easypromosapp.com/v24/ko/{EMAIL} - To test the ERROR answer

If you are validating customer codes instead of emails, the URLs are:

- https://wl.easypromosapp.com/v24/ok/{CUSTOMER_NUMBER} - For the case where everything is OK

- https://wl.easypromosapp.com/v24/ko/{CUSTOMER_NUMBER} - For the case where there is an ERROR

If, for example, you configure the always-error URL in the editor of your promotion as shown in the following image:

When testing the user experience, you will never be able to register in the promotion as an error will always be returned by the system.

Of course, the two testing URLs are only for you to run trials. You must implement a public URL where an email can be sent for validation. To prevent malicious use of these URLs, security tokens can be sent using the header fields."

Note: If this external web service call configuration does not fit your current service, it will be necessary to program and host an intermediary connector to interconnect the two services. If you need a connector, you can contact our Easypromos sales team to request a quote for the development, hosting, and maintenance of the connector.