How to build an API that creates a new entry in Craft CMS

Oscar de la Hera Gomez
A flower that represents Craft CMS with the text "Create New Entry POST Endpoint"

A step by step walkthrough in creating a POST RESTful endpoint in Craft CMS that uses a controller action to create a new entry.

The following tutorial walks you through how to use a Controller action to create an Subscriber entry, assuming that it doesn't already exist, through a POST Craft CMS endpoint. The tutorial forms part of our Open Source series that details how to create API endpoints that manage the subscribers to the delasign website.

This tutorial assumes that you have created a channel called subscribers, but we would like to note that the knowledge shared in this tutorial can be adapted to suit your needs.

We recommend downloading and setting up our Open Source Craft CMS starter project and checking out the main branch and carrying out the steps below. The changes carried out can be found on tutorial/new-subscriber.

git clone

Step One: Create your API endpoint base

A screenshot of Postman showing a succesful API call for the POST endpoint.

Please follow the tutorials linked below to create your RESTful API with an API key. We recommend testing it in Postman before continuing.

Please note that you must run this line after creating the API base for the API to register:

composer dump-autoload -a

Step Two: Complete the API

A screenshot of VSCode with our completed API. Code available below.

To complete the API you must first make sure that all the body parameters are present, then make sure that an entry with the details does not already exist and finally, create and save the entry.

A | Check that all the body parameters are present

Gather the body using the following line

$body = Craft::$app->request->getBodyParams();

Subsequently make sure that all the parameters are present and set them to variables that you can use later, through code similar to:

if (isset($body['YOUR_VARIABLE'])) { $YOUR_VARIABLE = $body['YOUR_VARIABLE']; } else { return $this->sendResponse(400,'Body is missing YOUR_VARIABLE variable.', null); }

Please note that if the variable doesn't exist we return a standardized bad request with an error stating that the variable is missing.

B | Make sure that an entry does not exist

In order for any Entry related code to be written, we must import the follow statement above your controller class

use craft\elements\Entry;

Subsequently, you must check that the subscriber does not exist. If it does, you must respond with an error that the subscriber already exists. In our case we did this by checking that the count for subscribers with an email variable equal to the email in the POST request body is greater than 0.

C | Create the entry

Finally, you must create the entry using code similar to the one below. This saveElement function produces a result that informs you if it succeeded or not. Use that to give your API response as to whether it succeeded or failed.

We recommend you consult the documentation linked below to learn more about Craft CMS's example on creating Entries in PHP.

Please note that we do not set a title as we have made the Title field equal to the email field when we created the Entry Type.

Here is a sample Controller that gathers all the subscriber and returns them as a JSON.

Step Three: Test

A screenshot of Postman showing a successful creation of a new subscriber using the code above.

Confirm that the API functions as expected by making a Postman call to your endpoint.

Any Questions?

We are actively looking for feedback on how to improve this resource. Please send us a note to with any thoughts or feedback you may have.

delasign logo

Book a Free Consultation.

An icon of an email.

Click here to email us.

Fill in the details below to book a free consultation or to let us know about something else. Whatever it is, we are here to help.

How can we help you ?

Contact Details