How do I create a contact using APIs?

This article describes how to maintain your forms and use our APIs to create a contact in Plezi

Florent avatar
Written by Florent
Updated over a week ago


It’s possible to use your own forms without going through Plezi’s, and you can link your forms and rely on the usual functionality of Plezi via our API. The process associated with creating a webservice requires a little development in terms of:

  • processing your existing form;

  • reproducing this form in Plezi.

But once this has been done, the contacts generated by this form will create contacts in Plezi while keeping the form-submission event, its source and its data.

In what cases should I replace Plezi forms?

This can be done when your forms have very specific functionalities, whether in terms of display or data-processing after it is submitted by the user, conditioned by specific rules that the Plezi form cannot replicate. For example:

  • an account-generation form, generating a password (see example below);

  • when an email is sent to a specific department based on a specific form choice;

  • the form supplies your CRM or another of your company’s information systems

  • the use of a CAPTCHA;

  • if you have a more complex approach to content, with hundreds of pieces of content already available on your site following submission of a form;

  • etc.

What steps do I take?

1. Read this document: this is particularly helpful for knowing where to find the necessary identifiers;

2. Create the form template and add it to a piece of content: this step is necessary for technical purposes and will also allow you to monitor all of your form’s statistics, as if it were really published on your website through Plezi. It involves creating a form replicating the fields in your existing form exactly. This Plezi form won’t be inserted anywhere but will serve as a carbon copy of the existing form. It’s this carbon copy that will allow Plezi to gather the contact information generated following the submission of the existing form;

Note for developers in charge of the following technical set-up:

A knowledge of the Plezi tool—particularly how to create forms—is necessary. Find out from your colleagues that have followed the Plezi onboarding process and decide together who should be in charge of creating this form in Plezi. For more information, please consult the Happy Academy articles on how to create a form template (coming soon) and adding a form to a piece of content;

3. Configure the request at your end

For more technical details, consult the complete API documentation, prepared BY our developers, FOR developers 😉 .

We have summarised it here:

Technical description of the request to put in place

Request URL

Request method

Use the GET method

Request header

You must be able to initiate the connection with two pieces of information, these being:

  • Your tenant (via the key: x-tenant-company)

  • Your API key (via the key: x-API-Key)

These pieces of information are available in Plezi: Settings > Plezi Configuration > Global, here:

If you don’t see the API Key, contact our CMS teams on our chat.

Request parameters

In the event that you decide to no longer add the field to your forms, you can retrieve the technical name of the field in Plezi by going to Settings > Web Form Templates. Then choose the form that you want and click on the small pink square.

Then choose the field that you’re interested in and there you’ll find the technical name.

For multiple-choice fields or dropdown lists, like the “Function” field, you also need to retrieve the IDs for each of the you field values in Plezi.

To do this:

  • Go to Configuration > Contact Qualification – Lists of values;

  • Choose your field from the dropdown menu on the left;

  • For each of your field values, click on the small pink square and retrieve the ID between /setting_records/ and /edit

Note: if your list has more than 20 values to retrieve, ask us so we can send the list of all value IDs for your field.

Visitor identification

You need to retrieve the dynamic data each time you call down the form for

visit = which resembles this type of format => f4260c09-7f32-4c7f-b4fd-9f4fa5feb931

visitor** = which resembles this type of format => 1497866343720459---554096f86261640006000000

For visitor, you need to retrieve only the first part before the separator “---“.

Which gives the following information to retrieve:


This data is available from the visitor’s cookies, cookies generated by the tracking script issued by the Plezi app:

  • Go to your website and inspect the page (left-click => Inspect)

  • Go to “Application”

  • In the “Name” column, find “visit” and “visitor” and enter these values

Identifying the source of the visitor

In your request, you can retrieve and access all the additional parameters raised by the visitor’s source URL, which will enable you to retrieve the right source for the contact in Plezi. These parameters are as follows:

  • Utm / utm_medium / utm_source

  • gclid

  • referrer

For example: account-creation form

For example, when you have a form that creates an account in your back office, you’ll need to retain the form which will integrate all of the professional information pertaining to your activity, but you will also need to pull up the information in Plezi in order to able to target this population.

To do this, follow these steps:

1. Create an offer-based piece of content called “Creating an account”;

2. Create a form associated with this content (using an existing template or creating a new template, creating the fields etc.) and reproduce this identically (the famous “carbon copy”);

3. Create the request by taking the necessary information in the publishing script for the Plezi form;

The tracking code indicates the following parameters: form_id and content_web_form_id. These are two parameters that will let you associate the action with the form and therefore to pull up the information in terms of the contact’s history. If points are associated with the content, then they’ll be taken into account for the contact.

<form id="foss-1234567890"></form><script src=''></script>

The request via CURL would then be in the following form.

4. Try it out: once the request has been made, all that’s left is to test that everything works. Complete the contact-creation form and check that:

  • The contact is loads in Plezi, with all the fields filled in, as well as the number of points earned (if requested when creating your content);

  • Its source has been identified;

  • The workflow configured in the Plezi “carbon copy” form works: thank-you message, sending an internal alert, sending the thank-you message. N.B. check the configuration of the form that already exists on your site. If this already has a workflow (e.g. sends a thank-you email with login details), make sure that you don’t duplicate this workflow with that configured in Plezi.

5. Important information : The statistics of the visits made on the form present on your website will NOT be counted on the form allowing the creation of the contact in Plezi.

The visit event on the Plezi form is counted from the moment the form is displayed, but in this situation the Plezi form is never displayed.

As a result, reports calculated on the basis of visits to content cannot be generated (e.g. conversion report by content).

Did this answer your question?