Developer API reference
Use a scoped business API key for a server-side integration.
Steps
Review the reference below and identify the minimum resource permissions your integration needs.
The business owner creates a key in the signed-in Help → Developer API section on an eligible plan.
Keep the key on your server and send it as a bearer token to the documented endpoint.
Check both HTTP status and GraphQL errors. Revoke and replace a key if it is exposed.
Good to know
Public documentation contains examples only. It does not expose business keys, private records or key-management controls. API integration access requires Scale; viewing this reference does not require a subscription.
Troubleshooting
If a request fails, check the key's validity, scope, resource names and query limits. Never paste a live key into support chat or a public code example.
ServicePace GraphQL API
Connect a server-side integration to your business using a scoped API key. Each request is restricted to the business that issued the key.
Only business owners can manage keys. Keep the full key on your server; never embed it in a website or mobile app.
Endpoint & authentication
https://servicepace.com/_api/graphqlSend JSON with query, optional variables, and operationName when selecting a named operation. Include these headers:
Authorization: Bearer sp_live_YOUR_API_KEY
Content-Type: application/jsonRead clients and their jobs
This example needs both customers:read and jobs:read. Remove the nested jobs field if your integration only needs clients.
query Customers($limit: Int!) {
customers(limit: $limit) {
id
name
email
jobs(limit: 5) { id service status }
}
}{
"limit": 10
}curl 'https://servicepace.com/_api/graphql' \
-H 'Authorization: Bearer sp_live_YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
"query": "query Customers($limit: Int!) {\n customers(limit: $limit) {\n id\n name\n email\n jobs(limit: 5) { id service status }\n }\n}",
"variables": {
"limit": 10
},
"operationName": "Customers"
}'{
"data": {
"customers": [
{
"id": "123",
"name": "Example Client",
"email": "customer@example.com",
"jobs": []
}
]
}
}Available queries
Each root query accepts limit: Int, defaulting to 50 and clamped to 1–100. Nested client jobs default to 25 and use the same bounds. Results are capped lists; cursor pagination, search and filtering are not currently supported.
| Query | Required permission | Available fields |
|---|---|---|
customers | customers:read | id, name, email, phone, address, city, notes |
jobs | jobs:read | id, customerId, customer, service, address, city, status, startAt, endAt |
invoices | invoices:read | id, customerId, title, status, createdAt, dueDate |
estimates | estimates:read | id, customerId, title, status, createdAt |
inventory | inventory:read | id, name, sku, description, quantity, unitCostCents |
receipts | receipts:read | id, jobId, merchant, purchasedAt, totalCents, createdAt |
employees | employees:read | id, name, email, archivedAt, createdAt |
appointments | appointments:read | id, customer, service, startAt, endAt, status |
customerLocations | customers:locations:read | id, customerId, label, address, city, isPrimary |
equipment | equipment:read | id, customerId, jobId, name, manufacturer, model, serialNumber |
payments | payments:read | id, invoiceId, amountCents, method, receivedAt |
customers.jobs requires jobs:read in addition to the client permission. IDs and date values are returned as strings. Monetary fields ending in Cents use cents; some are encoded as strings.
Create a customer
The external API currently supports one mutation: createCustomer, requiring customers:write. Supply a name of 2–150 characters. Email, phone, address, city and notes are optional strings, up to 2,000 characters each.
mutation CreateCustomer($input: CustomerInput!) {
createCustomer(input: $input) { id name email }
}{
"input": {
"name": "Example Client",
"email": "customer@example.com"
}
}Other write operations are not available in the external API. The inventory:write scope is reserved and does not currently enable inventory mutations.
Responses & errors
Read the data and errors properties of the JSON response. HTTP 200 can include GraphQL validation, permission or execution errors, so always check errors before using the result.
{
"errors": [
{
"message": "Invalid API key or missing jobs:read permission",
"extensions": {
"code": "FORBIDDEN"
}
}
],
"data": null
}- 401: No valid business API key, including expired or revoked keys.
- 400: Invalid JSON, invalid document, or a query that exceeds complexity limits.
- 413: Request body exceeds 30,000 characters.
- 405: Use POST for this endpoint.
Query limits
Query text is limited to 20,000 characters, with at most 70 field selections and 5 levels of depth. Fragments and subscriptions are not supported. Use your own backend for calls; direct cross-origin browser requests are not supported.
Legacy REST compatibility
Existing integrations can continue using /_api/v1-customers (GET and POST), and GET requests to /_api/v1-jobs, v1-invoices, v1-estimates, v1-inventory, v1-receipts, v1-employees and v1-appointments. They use the same bearer key and resource permissions.
Useful links
Workspace links require sign-in and the appropriate account access.Was this guide helpful?
Your feedback helps us keep the instructions useful.