How to make a GraphQL mutation query that creates an entry in Craft CMS

A step by step tutorial on using a GraphQL mutation query to create an entry in Craft CMS using Postman.

Oscar de la Hera Gomez
Written by Oscar de la Hera Gomez
First published on 12/24/2022 at 06:00
Last Updated on 02/15/2023 at 13:59
Three flowers that represent Craft CMS, GraphQL and Postman side by side. Beneath them sits the text "GraphQL Mutations Create an Entry."

A step by step tutorial on using a GraphQL mutation query to create an entry in Craft CMS using Postman.

The following tutorial walks you through how to make a GraphQL mutation query that creates a new Subscriber entry in Craft CMS. It requires you to have a Craft CMS project setup to work with GraphQL, a valid token and schema as well as a channel to save entries into.

SubscribeHow to make an API that makes GraphQL mutation queries in ServerlessHow to make a GraphQL mutation query that edits an entry in Craft CMSHow to make a GraphQL mutation query that deletes an entry in Craft CMSDownload Open Source Craft CMS ProjectHow to create & setup a Craft CMS projectHow to create a channel in Craft CMSHow to setup Craft CMS to work with the GraphQLHow to create a GraphQL schema in Craft CMSHow to create a GraphQL token in Craft CMS

Step One: Determine the Schema of the entry

A screenshot of the Craft CMS GraphiQl demonstrating a query that gathers all the Subscribers.

Using the GraphiQL, which can be accessed at YOUR_CRAFTCMS_URL.com/admin/graphiql, determine the schema of the entry that you wish to create.

In our case, it looks similar to the one below

Please note that for mutations to be able to create entries, under the "Choose the available mutations for this schema" section, your GraphQL schema must have checked off the "Create entries with the “ENTRY_TYPE” entry type" under the section of interest and have a valid authorization bearer token tied to it.

How to create a GraphQL schema in Craft CMSHow to create a GraphQL token in Craft CMS

Step Two: Setup Postman to work with an Authorization Bearer Token

A screenshot of Postman showing how to setup the authorization bearer token. Highlighted are the "Authorization" tab, the Type dropdown with the type set to "Bearer Token" and the Token input box.

Follow the tutorial below to set up Postman to work with an Authorization Bearer Token, ensuring that you have set the request to POST - which is required for saving entries.

How to make a GraphQL query with an Authorization Bearer Token in Postman

Step Three: Write the mutation query and variables

A screenshot of Postman showing the completed GraphQL mutation and variables.

Under the Body tab in the GraphQL section, create your save mutation.

Please note that all create mutations in Craft CMS must implement a authorId and title.

To build your mutation, consider the sample mutation GraphQL query and associated GraphQL variables below:

A | Write the Mutation Query

A screenshot of Postman with the completed GraphQL mutation. Highlighted is the Mutation Query.

In Postman, the mutation query is written in the Query input of the GraphQL option in the Body tab.

A mutation starts with the word mutation followed by its title (createSubscriber) and then within brackets the variables that you will use to save an entry.

These GraphQL variables start with a $ and pass in the type (i.e. $authorId: ID or $email: String) and must be matched in the GraphQL variables that are used to create the entry.

mutation createSubscriber($authorId: ID, $email: String, $subscriberName: String, $subscribed: Boolean)
How to filter for a Craft CMS site in a GraphQL Mutation

Subsequently, within the mutation query, you must set the entry type you wish to save to along with the variables that are used for each datapoint of the entry that you will create.

To do this write save_sectionHandle_entryHandle_Entry (i.e. save_subscribers_default_Entry) and within brackets write each schema field, along with the variable that is used to input data for that field (i.e. authorId: $authorId will use the $authorId query variable to write to the authorId field whilst the title: $email will use the $email query variable to write to the title field.

save_subscribers_default_Entry(authorId: $authorId, title: $email, email: $email, subscriberName: $subscriberName, subscribed: $subscribed)

Finally, within it write the variables that are required to create the entry. We have placed the full query below for your consideration

Please note that you must implement a title into your query to create an entry, even if the title is set to a field value within your Craft CMS entry definition.

How to set an entry title to a field value in Craft CMS

B | Write the GraphQL Variables

A screenshot of Postman with the completed mutation GraphQL call. Highlighted on the right side of the screen are the GraphQL variables that are used to create the entry.

In Postman, the GraphQL variables are written in the GraphQL Variables input of the GraphQL option in the Body tab.

The GraphQL Variables are written in JSON format and are the datapoints that are used to create the entry in Craft CMS which must be tied to the $ parameters that you implemented when writing your mutation.

For every $ parameter that you implemented when writing your mutation, there must be a JSON parameter with a matching datapoint of the type associated to the parameter (i.e. $email: string must be matched with "email": "EMAIL", whilst $authorId: ID must be matched with "authorID": Int).

Step Four: Test

A screenshot of Postman with a successful response.

When ready, press Send in Postman.

The response will appear at the bottom of the screen.

If you navigate to the section in Craft you will see that the entry was created.

A screenshot of Craft CMS Subscribers channel, showing that the API call created a subscriber.

Any Questions ?

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

SubscribeInquireView All PostsView All ServicesView All Work

Partner with us

We would love to get to know you and see how we can help your organization with its goals and needs.
Let's Talk

Stay Informed

Get occasional updates about our company, research, and product launches.
Subscribe