My First Call to the Web Services

To familiarize yourself with Dialog Insight's web services, there's no better way than to dive into the code right away. Let's make a first call together in your test project. For this example, we'll use the Contacts.Merge method, which is ideal for beginners. This method allows you to create a contact or update its information if it already exists in a single call.

Recommended Reading

If you start from zero with Dialog Insight, we recommend that you read the following articles to learn on the possibilities of Dialog Insight's platform and the web services:

• Introduction to Dialog Insight for Developers
• The Data Model of Dialog Insight
• Web Services Presentation

Step 1: Create a Test Project

When starting out with call testing with Dialog Insight, the best precaution is to start by creating a dedicated test project. This isolated environment acts as a sandbox: you can experiment, validate API calls, simulate campaigns, or manipulate data without risking the data actually used in production. A test project provides a secure workspace where you can test without fear of accidentally sending a message to a customer, corrupting data, or falsifying statistics. Unlike a real project, its purpose is not to support daily operations, but rather to allow developers to work freely, verify their scripts, and learn how to use the platform.

It may be tempting to use a project already in production, but the risks are high. A misconfigured API request or automation could trigger emails or SMS messages to real recipients. Import or update errors could modify or even delete critical information. Even simple test recordings can pollute your reports and performance indicators. Added to this is the legal issue: using real personal data in technical tests can pose a compliance problem with laws, particularly the GDPR or Law 25.

Option 1: Create a project from scratch

Go in your account and create a new project:

For more details on the steps to create a project, read Creating a Project.

Option 2: Duplicate an existing project

Go to the list of projects and click Duplicate at the end of the line of the project you want to duplicate: 

Wether you chose option 1 or 2, give a name and description to your project that will indicate explicitly it is a test project (e.g.,  "Project – TEST" or "Sandbox API "):

Step 2: Create a Web Services Key

Web services keys allow your application or scripts to interact with the platform via the API. Specifically, keys are used to authenticate and authorize your calls, whether in a test project or a project used to manage your contact data. Each key provides different access points: projects, tables, services (endpoints). Before creating your key, it's important to understand its role, its security implications, and best practices for managing it.

To get started, reate one for your test project. This will help you familiarize yourself with how it works. Limit permissions for this key to the test project to prevent unwanted actions in other projects in your company account. You can create separate keys for each environment (development, test, production).

→ Read the procedure to create a key

Step 3: Consult the endpoint and method

First, go to the documentation that corresponds to the environment used in your account.

On the left, in the web services list, find the Contacts endpoint and click the Merge method:In the documentation of each method, you will find a full description of the method and examples of request and responses in JSON.  

Step 4: Generate an Example

In the Contacts.Merge page, find the Try it button (it is a little subtle):

In the request editor, use the advanced mode and click Generate a sample: 

Step 5: Adapt the Example

The generated example serves as a useful basis for creating your call. All you have to do is add the information that's appropriate for your situation.

Authkey

When you have created your web services key, the key generated has the idkey and key parameters, which you have to add the values here. 

idProject    

To learn how to find your idProject, read this article.

Records

Add the contact data to be imported according to the structure set up in your project.

The example shows a common case with a project key with email (key_f_email) in which you specify the contact to add or update with their email address. The key may be different in your project. Sometimes the key is a customer number.

→ Learn more about primary keys and duplicate management

In Data, fields are written with "f_" followed by the field code (the destination for the data in the project). You can find the code of a field in the project's list, which can be accessed through Project → Data Management → Project Fields. In this way, "FirstName" becomes "f_FirstName".

Step 6: Send the Request

You don't need to use a URL in the test interface. It's added behind the scenes. Although the interface is named test, calls are actually sent to the project specified in the idProject. So be careful with the requests sent here.

When you are ready, click Submit request:

Results

If the answer is positive and there are no runtime errors, you will be able to see the contacts added to the list in your project. To consult the list, go to dans Audience → Contacts.