Guides
Start typing to search…

Getting started

Welcome to the Movement API. This guide will give you everything you need to start controlling Movement through its APIs, enabling you to query data, update records, set up calling campaigns and send text messages and emails. We'll cover basic API concepts, how you obtain an API key and making your first API call.

What is Movement?

Movement is a communications platform for progressive campaigns and organisations, enabling them to make calls, send texts and win for the people who matter to them.

Movement was built API-first. That means we expose nearly every single function in the app to API developers, and use all of these API routes ourselves within our app. We built Movement this way for two reasons:

  1. We know that campaigns use many different tools, so it's important that they all play nicely together.
  2. We know data is more powerful when it's all in one place, so we want to integrate with as many other tools as possible, as easily as possible.

Basic concepts

There are 3 fundamental concepts to be familiar with when it comes to understanding Movement's data model, which are the following:

  • Target, a person or organisation which can be contacted within Movement, via phone calls, SMS, email, or other channels.
  • Organisation, a part of a client's hierarchy. For example, the national office, a regional office, or a local branch. These can be infinitely nested and have multiple parents.
  • User, a person who can log into Movement. Always attached to an Organisation, which controls which Targets they have access to.

On top of this, campaigns are organised via:

  • Search, the targeting needed for the campaign
  • Campaign, the first class concept of an email blast, phonebank, SMS, or WhatsApp send
  • EmailBlast/TextMessageBlast, the sub-resource of the outbound communication

Quick start

Getting an API key

At the moment, you can only get an API key through contacting our helpdesk on [email protected]. We'll verify your identity and your use case, and create a new API user with the appropriate permissions.

Authentication

Authentication in Movement works through a straightforward bearer token, which is passed in the HTTP header Authorization as follows:

Authorization: Bearer <YOUR_API_KEY_GOES_HERE>

To ensure that this token does not leak, we only support HTTPS and do not upgrade HTTP connections. Please ensure therefore that you always use endpoints beginning with https://, as other calls will fail.

Please note that most API keys are required to be locked to certain calling IP addresses for security. If you need an exception for this, due to dynamic IP addresses on your hosting provider, please let us know.

Your subdomain

All requests must be made to your subdomain, e.g. https://subdomain.yourmovement.org. This is the same domain as you'd use to access Movement.

Making your first API call

To test your token is working properly, we'll make a GET request to the /users/me endpoint. This endpoint acts as a simple health check on the Movement API, and will not change any resources or affect your account in any way.

curl -sS -X GET "https://subdomain.yourmovement.org/api/me" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY_GOES_HERE>'

If this call was successful, then you should see a short JSON blob with some details about your user, as in the example below:

{"id":2,"first_name":"Example API User","last_name":null,"name":"Example API User","client_name":"Example Client"}

Next steps

Now you're successfully making authenticated calls to Movement with your API key, you're ready to dive into the rest of the API.

We're still building out our documentation, so more guides will be coming in the future on common things like bulk updating your content records from another CRM or sending a text message blast, but for the meantime, we recommend checking out our extensive API reference using the sidebar.

If you have any questions or feedback, even if it feels small, please don't hesitate to contact us on [email protected], and we'll respond as quickly as we can.

Updated 8 days ago