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.

Quickly jump around this post with this index:


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:

Base URL

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


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

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

Header name Type Description
Content-Type String Describes the nature of the data in the request body. It should always be set to application/json
formilla_auth_token String The Secure Token for your account.

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

Parameter Type Description
UserId String A unique identifier for the contact. It’s required if Email isn’t provided.
Email String The contact’s email address. It’s required if UserId isn’t provided.
FirstName String The contact’s first name.
LastName String The contact’s last name.
Phone String The contact’s phone number.
SignedUp_date Date (unix timestamp) The datetime when the contact signed up in unix timestamp format.
IsUnsubscribed Boolean Whether the contact is unsubscribed from emails. Default value: false
CustomAttributes JSON Object that contains key/value pairs. Use this parameter to pass any custom data you want to track about your contacts.


  • 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.


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("");
var request = new RestRequest("/contacts", Method.POST);

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

request.RequestFormat = DataFormat.Json;

var response = client.Execute(request);

if (response.StatusCode == HttpStatusCode.OK)
    // Contact was added successfully!
    // 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.2-contact-landing-page-new-contact

API Responses

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

Code Description
200 OK – the request has succeeded.
400 Bad Request – invalid request due to one of the following reasons:

  • No contact UserId or Email were supplied
  • Custom Attribute name or Event name contains invalid characters
  • Custom Attribute has an invalid value
  • You’ve reached the custom attribute limit
  • Contact Integration feature is not available for your account
403 Forbidden – unauthorized request due to an invalid formilla_auth_token or you’ve exceeded your current package limit of contacts.
404 Not Found – the requested resource was not found.

  • Message: No HTTP resource was found that matches the request URI […]
  • MessageDetail: No type was found that matches the controller named […]
429 You have reached the REST API max limit.

  • Message: API max limit has been reached. Please limit requests to 40 per 5 seconds.
Server Error – likely something went wrong on Formilla’s end.
503 Service Unavailable – API is temporarily unavailable due to scheduled maintenance.

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

Join the Formilla blog!

We offer actionable advice about live chat, chat bots, marketing automation, customer service, and sales. Sign up and we'll send you the best of the blog, from articles to infographics, every two weeks.

100% privacy. Unsubscribe any time.