Syncro API Patterns

Syncro MSP API Patterns

Overview

The Syncro MSP API provides access to tickets, customers, assets, invoices, and more. This skill covers authentication, pagination, rate limiting, error handling, and best practices for API integration.

Authentication

API Key Authentication

Syncro uses Bearer token authentication with API keys:

GET /api/v1/tickets
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Getting Your API Key

1. Log into your Syncro MSP account
2. Go to Admin > API Tokens (or User Profile)
3. Generate a new API token
4. Copy and securely store the token

Environment Variables

export SYNCRO_API_KEY="your-api-key-here"
export SYNCRO_SUBDOMAIN="your-subdomain"  # e.g., "acme" for acme.syncromsp.com

Base URL Format

The API base URL uses your subdomain — requests to the wrong subdomain authenticate against a different tenant, so verify it matches the account you intend to hit:

https://{subdomain}.syncromsp.com/api/v1/

Example:

https://acme.syncromsp.com/api/v1/tickets

Pagination

Page-Based Pagination

Syncro uses page-based pagination:

GET /api/v1/tickets?page=1
GET /api/v1/tickets?page=2
GET /api/v1/tickets?page=3

Pagination Parameters

There is no page-size parameter — per_page is fixed at 25 by the server and reported back in meta, so a large result set always costs total_pages requests.

Response Metadata

Responses include pagination information. Note the collection is keyed by resource name (tickets, customers, ...), not a generic data key:

{
  "tickets": [...],
  "meta": {
    "total_entries": 156,
    "total_pages": 7,
    "page": 1,
    "per_page": 25
  }
}

See references/examples.md for a working page-walking implementation.

Rate Limiting

Rate Limit Policy

Syncro enforces a rate limit of 180 requests per minute per IP address. Because the limit is per-IP rather than per-key, separate integrations sharing an egress address contend for the same budget.

Rate Limit Response

When rate limited, you receive:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": "Rate limit exceeded. Please wait before making more requests."
}

At 180 req/min, a ~350ms delay between calls keeps a single-threaded client safely under the ceiling.

See references/examples.md for retry-with-backoff and throttled batch-processing implementations.

Common Query Parameters

Error Handling

HTTP Status Codes

Error Response Format

Validation failures (422) return a per-field errors array in addition to the top-level error string — read the array, not just the string, to know which field was rejected:

{
  "error": "Validation failed",
  "errors": [
    {
      "field": "customer_id",
      "message": "is required"
    }
  ]
}

See references/examples.md for a request wrapper that maps these statuses to actionable errors.

Request Patterns and Endpoints

Syncro follows conventional REST verbs: GET to read, POST to create, PUT to update, DELETE to remove. Sub-resource actions are POST to a named path (e.g. /tickets/{id}/comment, /invoices/{id}/email).

See references/api.md for the complete endpoint catalog, request shapes, and cURL examples.

Best Practices

1. Cache reference data - Reduce API calls for static lookups
2. Paginate large requests - Don't fetch unbounded result sets
3. Log API calls - Enable debugging and audit trails when the per-IP rate limit is shared across integrations

Related Skills

• Syncro Tickets - Ticket management
• Syncro Customers - Customer management
• Syncro Assets - Asset management
• Syncro Invoices - Invoice management