Syncro User Management API Guide

Auth method: API Key (Bearer token in Authorization header)

Setup steps

1. Log in to your Syncro account.
2. Navigate to Admin > API Tokens.
3. Click 'New Token', give it a name, and save.
4. Copy the generated token.
5. Pass the token in the Authorization header as: Authorization: Bearer {token}

Required scopes

List contacts

• Method: GET
• URL: https://{subdomain}.syncromsp.com/api/v1/contacts
• Watch out for: Results are paginated at 25 per page by default. Use the page param to iterate.

Request example

GET /api/v1/contacts?page=1
Authorization: Bearer {token}

Response example

{
  "contacts": [
    {"id": 101, "firstname": "Jane", "lastname": "Doe",
     "email": "jane@example.com", "customer_id": 55}
  ],
  "meta": {"total_pages": 3, "total_count": 72}
}

Get contact by ID

• Method: GET
• URL: https://{subdomain}.syncromsp.com/api/v1/contacts/{id}
• Watch out for: Returns 404 if the contact ID does not exist or belongs to a different subdomain.

Request example

GET /api/v1/contacts/101
Authorization: Bearer {token}

Response example

{
  "contact": {
    "id": 101,
    "firstname": "Jane",
    "lastname": "Doe",
    "email": "jane@example.com",
    "customer_id": 55
  }
}

Create contact

• Method: POST
• URL: https://{subdomain}.syncromsp.com/api/v1/contacts
• Watch out for: customer_id is required; contacts cannot exist without a parent customer record.

Request example

POST /api/v1/contacts
Authorization: Bearer {token}
Content-Type: application/json

{"firstname":"John","lastname":"Smith",
 "email":"john@example.com","customer_id":55}

Response example

{
  "contact": {
    "id": 202,
    "firstname": "John",
    "lastname": "Smith",
    "email": "john@example.com",
    "customer_id": 55
  }
}

Update contact

• Method: PUT
• URL: https://{subdomain}.syncromsp.com/api/v1/contacts/{id}
• Watch out for: Uses PUT (full or partial update accepted in practice); verify field behavior against the Swagger spec.

Request example

PUT /api/v1/contacts/202
Authorization: Bearer {token}
Content-Type: application/json

{"phone":"555-1234"}

Response example

{
  "contact": {
    "id": 202,
    "phone": "555-1234"
  }
}

Delete contact

• Method: DELETE
• URL: https://{subdomain}.syncromsp.com/api/v1/contacts/{id}
• Watch out for: Deletion is permanent. Associated tickets may retain the contact reference as orphaned data.

Request example

DELETE /api/v1/contacts/202
Authorization: Bearer {token}

Response example

HTTP 200 OK
{}

List customers (organizations)

• Method: GET
• URL: https://{subdomain}.syncromsp.com/api/v1/customers
• Watch out for: Customers and contacts are separate objects. Contacts are sub-records of customers.

Request example

GET /api/v1/customers?page=1
Authorization: Bearer {token}

Response example

{
  "customers": [
    {"id": 55, "firstname": "Acme", "email": "admin@acme.com"}
  ],
  "meta": {"total_pages": 1, "total_count": 1}
}

Create customer

• Method: POST
• URL: https://{subdomain}.syncromsp.com/api/v1/customers
• Watch out for: Technician (internal) users cannot be created via the API; only customer-side contacts and organizations are manageable through the REST API.

Request example

POST /api/v1/customers
Authorization: Bearer {token}
Content-Type: application/json

{"firstname":"Acme Corp","email":"admin@acme.com"}

Response example

{
  "customer": {
    "id": 56,
    "firstname": "Acme Corp",
    "email": "admin@acme.com"
  }
}

Get customer by ID

• Method: GET
• URL: https://{subdomain}.syncromsp.com/api/v1/customers/{id}

Request example

GET /api/v1/customers/55
Authorization: Bearer {token}

Response example

{
  "customer": {
    "id": 55,
    "firstname": "Acme Corp",
    "email": "admin@acme.com",
    "created_at": "2023-01-10T12:00:00Z"
  }
}

• Rate limits: Syncro enforces rate limiting on API requests. The official docs note a limit but do not publish a specific per-minute or per-hour number publicly.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Official docs do not specify rate-limit headers or Retry-After behavior. HTTP 429 is returned when the limit is exceeded.
• Pagination method: offset
• Default page size: 25
• Max page size: 100
• Pagination pointer: page

• Webhooks available: Yes
• Webhook notes: Syncro supports outbound webhooks triggered by platform events. Webhooks are configured in Admin > Webhooks and deliver JSON payloads via HTTP POST to a specified URL.
• Alternative event strategy: Poll the REST API for changes if webhook delivery is not suitable.
• Webhook events: ticket.created, ticket.updated, ticket.resolved, customer.created, customer.updated, contact.created, contact.updated, invoice.created, payment.received

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• Syncro does not document a SCIM 2.0 endpoint for technician provisioning.
• No IdP (Okta, Entra ID, Google Workspace, OneLogin) SCIM integration is documented in official help or developer docs.
• Technician user management is UI-only within the Syncro admin panel.

Three integration patterns are well-supported by the current API surface.

Provisioning a new customer contact from an external system: check for the parent customer via GET /api/v1/customers?query={value}, create it if absent via POST /api/v1/customers, then create the contact via POST /api/v1/contacts with customer_id set to the returned customer ID.

Contacts cannot exist without a valid parent customer - omitting customer_id returns a validation error.

Syncing contact updates from an external directory: retrieve the stored contact via GET /api/v1/contacts/{id}, diff against your source of truth, and issue PUT /api/v1/contacts/{id} with updated fields.

There is no PATCH endpoint;

PUT is the only update method.

Sending partial fields may work in practice but verify against the Swagger spec at api-docs.syncromsp.com to avoid unintentional field nullification.

Event-driven enrichment via webhooks: configure a customer.created webhook in Admin > Webhooks pointing to your ingest endpoint.

On receipt, extract the customer ID and follow up with GET /api/v1/customers/{id} - webhook payloads do not guarantee full object detail, so the follow-up GET is required for complete data.

Provision a new customer contact from an external system

1. Check if the parent customer exists: GET /api/v1/customers?query={email_or_name}
2. If not found, create the customer: POST /api/v1/customers with firstname and email.
3. Note the returned customer id.
4. Create the contact: POST /api/v1/contacts with firstname, lastname, email, and customer_id set to the customer id from step 3.
5. Store the returned contact id in your external system for future updates.

Watch out for: Contacts require a valid customer_id. Attempting to create a contact without a pre-existing customer will fail with a validation error.

Sync contact updates from an external directory

1. Retrieve the contact by stored ID: GET /api/v1/contacts/{id}
2. Compare fields (email, phone, address) against your directory source of truth.
3. If differences exist, issue PUT /api/v1/contacts/{id} with the updated fields.
4. Log the updated_at timestamp from the response for audit purposes.

Watch out for: There is no PATCH endpoint; use PUT. Sending only changed fields may work but verify against the Swagger spec to avoid unintentional field nullification.

Detect new customers via webhook and enrich in external CRM

1. Configure a webhook in Syncro Admin > Webhooks targeting your CRM ingest endpoint.
2. Select the customer.created event.
3. On receipt of the webhook payload, extract the customer id.
4. Call GET /api/v1/customers/{id} to retrieve full customer details.
5. Write the enriched record to your CRM.

Watch out for: Webhook payloads may not include all customer fields. Always follow up with a GET request to retrieve the complete object.

The primary integration trap is scope mismatch: the Syncro REST API is scoped to customer-facing contacts and organizations, not to the technician identity layer.

Any identity graph that needs to reflect internal staff provisioning state - who has access, at what permission level, and whether they are active - cannot be built from the API alone. That data lives exclusively in the UI.

A secondary trap is token permission inheritance. Because tokens carry the creating technician's permissions with no independent scope configuration, a token rotation or ownership change silently alters what the integration can read or write. There is no way to issue a least-privilege token for a specific endpoint subset.

Finally, the undocumented rate limit creates operational risk for high-frequency sync jobs. Without a published limit or Retry-After header, integrations must implement conservative backoff logic empirically rather than against a known ceiling.

The Swagger spec at api-docs.syncromsp.com is the authoritative field reference and should be treated as the source of truth over help center articles, which may lag API changes.