MoveRight API

MoveRight API — Overview

MoveRight is built API-first. Every job, customer, event, charge, invoice, and transaction is accessible via GraphQL — the same API the MoveRight web app uses. This page covers authentication, zones, and how to navigate the full reference.

API Reference Sections

Overview & Authentication

You are here

GraphQL Reference

Queries, mutations, pagination, filtering

Intake / Lead Form API

Embed forms, POST leads programmatically

Datadip Voice Endpoint

Real-time caller lookup for phone systems

Base URL & Playground

GraphQL endpoint

https://moveright.app/api/graphql

Interactive playground

Open playground →

Introspection enabled. Click "Docs" in the right panel to explore the full schema.

MoveRight uses GraphQL as its primary API. You send POST requests to a single endpoint with a JSON body containing your query or mutation, optional variables, and your authentication headers. The playground performs full introspection — the best way to discover available types and fields is to open it and browse the schema using the Docs tab.

Authentication

All API requests that read or modify protected data require authentication via an Authorization header. There are three methods:

Method 1 Basic Authentication

Pass a semicolon-delimited email:password string preceded by Basic. Simplest for testing.

Authorization: Basic your@email.com:yourpassword

Method 2 Refresh Token

Pass your refresh token preceded by RefreshToken. The refresh token is long-lived and suitable for server-side integrations.

Authorization: RefreshToken your_refresh_token_here

Get your refresh token by running the authenticate mutation:

mutation {
  authenticate(
    email: "your@email.com"
    password: "yourpassword"
  ) {
    userId
    jwt
    jwtExpires
    refreshToken
    refreshTokenExpires
  }
}

Method 3 JWT Bearer Token

Use the short-lived JWT from the authenticate response as a Bearer token. JWTs expire — use the refresh token to re-authenticate programmatically.

Authorization: Bearer your_jwt_token_here

Zones

MoveRight data is organized by zones — a hierarchical structure where one zone can have child zones (e.g., a franchisor zone containing multiple franchise zones). To query data in a specific zone, pass its ID as a query parameter or header:

Via query parameter

POST /api/graphql?zone=your-zone-id

Via header

x-zone: your-zone-id

When querying jobs, the zone controls which records are returned. By default, the query returns jobs in the specified zone and all of its descendants. You can change this with the zoneDir filter:

zoneDir value	Behavior
lte (default)	Returns jobs in this zone and all child/descendant zones
gte	Returns jobs in this zone and all parent/ancestor zones
eq	Returns jobs in exactly this zone only

Context & Permissions

MoveRight uses a zone + role context system for permissions. Your JWT encodes up to 64 context claims, each a zone:role pairing. The context tells the API which zone and role to evaluate permissions for on the current request.

Set the context by passing a zone:role string as a query parameter or header:

Query parameter

?context=zone-id:Admin

Header

x-context: zone-id:Admin

Tip: If you only pass ?zone=zone-id without a role, MoveRight resolves a context from your refresh token for that zone. For most integrations, passing just ?zone= is sufficient.

Making Your First Request

All GraphQL requests are HTTP POST to /api/graphql. The body is JSON with a query string and optional variables object.

curl -X POST "https://moveright.app/api/graphql?zone=YOUR_ZONE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic your@email.com:yourpassword" \
  -d '{
    "query": "{ jobs(limit: 5) { total jobs { id code stage } } }"
  }'

Pro tip: Use the playground first

Before writing any code, open moveright.app/api/graphql in your browser, authenticate via the Headers panel, and explore the schema. The "Docs" tab on the right shows every available type, field, query, and mutation. Introspection is fully enabled — no separate schema download needed.

Continue Reading

Core API

GraphQL Reference →

Queries and mutations for jobs, events, invoices, charges, transactions, and users.

Lead Capture

Intake Form API →

POST leads from any website or form builder. Full field reference and token setup.

Voice / IVR

Datadip Voice →

Real-time caller lookup and inbound call record creation for external phone systems.