Integrating Customer Data with the Formilla REST API

The Formilla REST API provides the ability to push customer data from your system to Formilla. By pushing your data into Formilla, you can send automatic email and in-app messages to your customers based on any custom data important to your business.

This post will give you an overview about how to use the REST API, with examples on how to create or update your contact data, what API response codes to expect, and more.

Note: if you’re using Formilla with a Wix website, the Formilla REST API is not supported.

Setup

The Formilla API is RESTful and responds with standard HTTP response codes to indicate the result of the request. It is disabled by default in your Formilla account, so you can start by enabling it with the steps in this post.

You can use any HTTP/REST library available for your programming language to communicate with our API, such as:

• PHP cURL – If you use PHP
• RestSharp – If you use C#
• Unirest – If you use Java

Base URL

All Formilla API URLs must start with the following base URL:

https://api.formilla.com/api

Authentication

When you enable the REST API from the Security page, a Token will be generated for your account.

Each request you make to the Formilla API must include the token in the request header.

Note: of course, be sure to keep your API Token a secret and do not share it with anyone!

Create (or Update) a Contact

Use this method to create a new contact or to update an existing one.

POST /contacts

Request body attributes

Notes

• If UserId and Email aren’t provided, no action will be performed by the API.
• If UserId and Email are both provided, we’ll try to first find an existing contact by UserId and if it’s not found, we’ll try by Email. If we can’t find it either, a new contact will be created.
• When an existing contact is found, their data will be overwritten with the new data supplied via the API.
• The  CustomAttributes parameter must be a valid JSON object. In our JavaScript API post we explain the guidelines for Contact Custom Attributes.

Example

Check out the following C# example where a new contact is created in Formilla. Please note that the RestSharp library is used in this example.

var formillaContact = new
{
	UserId = "100",
	Email = "[email protected]",
	FirstName = "Tom",
	LastName = "London",
	Phone = "+1 786-233-9885",
	SignedUp_date = 1524823200,
	CustomAttributes = new
	{
		PlanName = "Premium",
		SubscriptionEnds_date = 1565395200,
		CommissionRate = 7.5m
	}
};

var client = new RestClient("https://api.formilla.com/api");
var request = new RestRequest("/contacts", Method.POST);

request.AddHeader("formilla_auth_token", "eyJDdXN0b21lclNpdGVHdWlkIjoiY3NjZDUzN2EtNGEwMC00MDA3LWFiNzgtYzNmM2IxN2E3MzBhIiwiUHVibGljQXBpQXV0aFRva2VuIjoiQThDOEE4RkQtRTZFNy00QUQwLUI2MzYtMzVDMjM5QkIwQTY4In0="); // Replace this token with yours

request.RequestFormat = DataFormat.Json;
request.AddBody(formillaContact);

var response = client.Execute(request);

if (response.StatusCode == HttpStatusCode.OK)
{
    // Contact was added successfully!
}
else
{
    // Handle errors
}

As you may have noticed, this example returns a 200 OK response if the contact is created successfully. See the full list of responses at the bottom of this post.

Remember, you can find your contacts in your Formilla account by clicking Contacts from the left menu.

API Responses

The Formilla REST API returns standard HTTP response codes on each request to indicate the result. Here is a list of them:

Please feel free to contact us at [email protected] if you have any troubles or questions! ?