In this post I show you how you can map custom routes for your Umbraco Api Controller.

Lets say you are writing an import controller and you want to customise the route to something like this:

Then first you will need to decorate the class and the action like this:

using Newtonsoft.Json.Linq;
using System.Web.Http;
using Umbraco.Web.WebApi;

namespace CodeShare.Web.Controllers.Api
    public class ProductImportApiController : UmbracoApiController
        public IHttpActionResult ImportProducts()
            dynamic data = new JObject();
            data.message = "The product import was successful";
            return Ok(data);

And the code to map the routes correctly for you is here:

using System.Web.Http;
using Umbraco.Core.Composing;

namespace CodeShare.Core.Composing
    [RuntimeLevel(MinLevel = RuntimeLevel.Run)]
    public class RegisterCustomApiRoutesComposer : ComponentComposer<RegisterCustomApiRoutesComponent>
    { }

    public class RegisterCustomApiRoutesComponent : IComponent
        public void Initialize()

        public void Terminate()
            //nothing to terminate

Make sure you do a clean and rebuild and you should be good to go.


Thanks to Anders Bjerner for pointing the following out.

You can also add parameters:

public object GetEmployeeById(string id, string type = null) { }

You can even add constraints:


Paul Seal

Umbraco MVP and .NET Web Developer from Derby (UK) who specialises in building Content Management System (CMS) websites using MVC with Umbraco as a framework. Paul is passionate about web development and programming as a whole. Apart from when he's with his wife and son, if he's not writing code, he's thinking about it or listening to a podcast about it.

Proudly sponsored by


  • Moriyama build, support and deploy Umbraco, Azure and ASP.NET websites and applications.

  • CI/CD service for Windows, Linux and macOS
  • Build, test, deploy your apps faster, on any platform.

  • is the easy error logging and uptime monitoring service for .NET.
  • Take back control of your errors with support for all .NET web and logging frameworks.
uSync Complete

  • uSync.Complete gives you all the uSync packages, allowing you to completely control how your Umbraco settings, content and media is stored, transferred and managed across all your Umbraco Installations.

  • More than a theme for Umbraco CMS, take full control of your content and design with a feature-rich, award-nominated & content editor focused website platform.

  • Affordable, Geo-Redundant, Umbraco hosting which gives back to the community by sponsoring an Umbraco Open Source Developer with each hosting package sold.