Skip to main content

Sync Organizations with a PSA

Your PSA is where clients are created, renamed and closed. This example shows how to keep SparkLogs organizations matching it. It has two parts: first read the organizations SparkLogs has, then create, update or delete organizations to match the PSA.

The link between the two systems is the client id. Each organization can hold a psa_client_id and an rmm_client_id, and you can look an organization up by either.

What the token needs​

ToGive a workspace tokenWith the scope
Read onlyany role at the organization that holds your clientsworkspace:read
Create, rename and closeDeployment Manager or Engineer therefleet:write
Also move organizations between parentsOrganization Administrator at the current parent and at the new onefleet:write

A token with access to part of the tree syncs only that part. To see where that part starts, read your access.

Read the current organizations​

First run: load everything​

GET/workspaces/{workspace_id}/organizations
List organizations

Scope: workspace:read

Pass deleted=include.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?deleted=include" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organizations retrieved",  "next_cursor": null,  "organizations": [    {      "id": "0a9e0000-0000-4000-8000-000000000100",      "parent_id": null,      "path": [        "0a9e0000-0000-4000-8000-000000000100"      ],      "name": "Northwind clients",      "description": "Every client of Northwind IT Services",      "rmm_client_id": null,      "psa_client_id": null,      "created_at": "2026-11-01T09:00:00Z",      "updated_at": "2026-11-01T09:00:00Z",      "deleted_at": null    },    {      "id": "0a9e0000-0000-4000-8000-000000000101",      "parent_id": "0a9e0000-0000-4000-8000-000000000100",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000101"      ],      "name": "Lakeside Clinic",      "description": "Family practice, two sites",      "rmm_client_id": "LAKESIDE-01",      "psa_client_id": "10042",      "created_at": "2026-11-02T09:00:00Z",      "updated_at": "2026-11-02T09:00:00Z",      "deleted_at": null    },    {      "id": "0a9e0000-0000-4000-8000-000000000102",      "parent_id": "0a9e0000-0000-4000-8000-000000000101",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000101",        "0a9e0000-0000-4000-8000-000000000102"      ],      "name": "Finance",      "description": null,      "rmm_client_id": null,      "psa_client_id": null,      "created_at": "2026-11-03T10:00:00Z",      "updated_at": "2026-11-03T10:00:00Z",      "deleted_at": null    },    {      "id": "0a9e0000-0000-4000-8000-000000000103",      "parent_id": "0a9e0000-0000-4000-8000-000000000100",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000103"      ],      "name": "Oakridge Medical",      "description": null,      "rmm_client_id": "OAKRIDGE-01",      "psa_client_id": null,      "created_at": "2026-11-02T09:00:00Z",      "updated_at": "2026-11-04T11:00:00Z",      "deleted_at": null    },    {      "id": "0a9e0000-0000-4000-8000-000000000105",      "parent_id": "0a9e0000-0000-4000-8000-000000000100",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000105"      ],      "name": "Harbor Dental",      "description": null,      "rmm_client_id": null,      "psa_client_id": null,      "created_at": "2026-11-02T09:00:00Z",      "updated_at": "2026-11-05T08:00:00Z",      "deleted_at": null    },    {      "id": "0a9e0000-0000-4000-8000-000000000104",      "parent_id": "0a9e0000-0000-4000-8000-000000000100",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000104"      ],      "name": "Summit Accounting",      "description": null,      "rmm_client_id": null,      "psa_client_id": null,      "created_at": "2026-11-02T09:00:00Z",      "updated_at": "2026-11-06T14:00:00Z",      "deleted_at": "2026-11-06T14:00:00Z"    }  ],  "watermark": "2026-11-08T09:00:00Z"}

Page to the end with cursor, keep one row per id, and store the watermark once the last page is in. See Paging and sync for each of these.

Every later run: load what changed​

GET/workspaces/{workspace_id}/organizations
List organizations

Scope: workspace:read

Pass updated_since set to the stored watermark, with deleted=include.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?updated_since=2026-11-08T09%3A00%3A00Z&deleted=include" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organizations retrieved",  "next_cursor": null,  "organizations": [    {      "id": "0a9e0000-0000-4000-8000-000000000105",      "parent_id": "0a9e0000-0000-4000-8000-000000000100",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000105"      ],      "name": "Harbor Dental",      "description": null,      "rmm_client_id": null,      "psa_client_id": "10057",      "created_at": "2026-11-02T09:00:00Z",      "updated_at": "2026-11-09T16:00:00Z",      "deleted_at": null    }  ],  "watermark": "2026-11-10T09:00:00Z"}

A rename, a change of client id, a delete, a restore and a move each put the organization in this list. Store the new watermark after the last page.

Two kinds of change need extra work:

  • A move. Moving an organization changes the path of everything below it, but only the moved organization appears as changed. If you store path, read the subtree again when you see an organization whose parent_id changed, by listing with root_id set to its id. The parent_id of the organizations below it does not change.
  • A change in what the token can see. Organizations that come into or leave the token's reach do not appear as changes. Run the full load on a schedule, weekly for example, and treat it as the truth.

Make organizations match the PSA​

For each company in the PSA, look it up first:

GET/workspaces/{workspace_id}/organizations
List organizations

Scope: workspace:read

Filter by psa_client_id, with deleted=include. Add parent_id to look under one part of the tree.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?psa_client_id=10042&deleted=include" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organizations retrieved",  "next_cursor": null,  "organizations": [    {      "id": "0a9e0000-0000-4000-8000-000000000101",      "parent_id": "0a9e0000-0000-4000-8000-000000000100",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000101"      ],      "name": "Lakeside Clinic",      "description": "Family practice, two sites",      "rmm_client_id": "LAKESIDE-01",      "psa_client_id": "10042",      "created_at": "2026-11-02T09:00:00Z",      "updated_at": "2026-11-02T09:00:00Z",      "deleted_at": null    }  ],  "watermark": "2026-11-10T09:00:00Z"}

If your RMM installs agents with an RMM client id, look up by rmm_client_id as well, in a second call. The RMM id comes from wherever you map PSA companies to RMM clients today, often a field on the PSA company. See Onboard a client for why an organization should record both ids.

Then act on what comes back.

The lookup returnsIn the PSADo
NothingActive companyCreate the organization.
One live organizationA different name or RMM idUpdate it.
One live organizationA different parentMove it.
One live organizationCompany closedDelete it, after its agents. See Offboard a client.
One deleted organizationCompany active againRestore it.
Two or moreAnythingStop. Two organizations record the same client id, and a person has to decide which is right.

Before giving a client id to an organization, you can check it for duplicates. The check also counts organizations the token cannot see. The lookup returns only organizations the token can see. It needs fleet:write, so a read-only sync token cannot call it.

Example API calls​

A new company:

POST/workspaces/{workspace_id}/organizations
Create an organization

Scope: fleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Pine Ridge Dental",    "parent_id": "0a9e0000-0000-4000-8000-000000000100",    "psa_client_id": "10061",    "rmm_client_id": "PINERIDGE-01"  }'
Response 200
{  "message": "organization created",  "id": "0a9e0000-0000-4000-8000-000000000106",  "cache_clear_status": "ok"}

A new site under a company:

POST/workspaces/{workspace_id}/organizations
Create an organization

Scope: fleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Finance",    "parent_id": "0a9e0000-0000-4000-8000-000000000101"  }'
Response 200
{  "message": "organization created",  "id": "0a9e0000-0000-4000-8000-000000000102",  "cache_clear_status": "ok"}

A changed name or client id:

PATCH/workspaces/{workspace_id}/organizations/{id}
Update an organization

Scope: fleet:write

Request
curl -X PATCH \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000103" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "psa_client_id": "10063"  }'
Response 200
{  "message": "organization updated",  "id": "0a9e0000-0000-4000-8000-000000000103"}

A different parent:

POST/workspaces/{workspace_id}/organizations/{id}/move
Move an organization

Scope: fleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000102/move" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "parent_id": "0a9e0000-0000-4000-8000-000000000103"  }'
Response 200
{  "message": "organization moved",  "cache_clear_status": "ok"}

A closed company, then one that came back:

DELETE/workspaces/{workspace_id}/organizations/{id}
Delete an organization

Scope: fleet:write

Request
curl -X DELETE \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organization deleted",  "cache_clear_status": "ok"}
POST/workspaces/{workspace_id}/organizations/{id}/restore
Restore a deleted organization

Scope: fleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104/restore" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organization restored",  "cache_clear_status": "ok"}

Restoring an organization does not restore its agents. Restore each one that should come back.

Updating fields​

An update changes only the fields you send. A field you leave out keeps its value. To clear a client id or the description, send it as null. An empty string clears it too. A name cannot be cleared: null returns 400. An update cannot change the parent: use the move call.

If a step fails​

CallResponseCause and fix
Update, delete, restore or move403 APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONThe organization does not exist, or the token cannot change it. The API returns the same response for both.
Delete409 APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTYIt still has live agents, ingest keys or child organizations. Remove those first.
Restore409 APP_API_ERR_CANNOT_RESTORE_PARENT_DELETEDIts parent is deleted. Restore the parent first.
Move400 naming parent_idThe destination is the organization itself, something below it, a deleted organization, or too deep in the tree.
Move409 APP_API_ERR_CONFLICTThe tree changed while the move ran: another move landed first, or a new organization collided with this one. Nothing moved. Read the organizations again before you retry.
Any list400 naming cursorThe cursor was sent with different filters than the page it came from.

Idempotency (safety of repeated API calls)​

Updating, deleting, restoring and moving end in the same state when repeated, and each returns 200 the second time. Creating does not: it makes a second organization. Always run the lookup immediately before a create.

Two integrations writing the same organization do not block each other, and the last write wins. Let only one system write each field.

What the API does not do​

  • It does not notify you of changes: a sync has to poll.
  • It does not delete an organization together with its agents in one call.
  • It reads an organization's custom fields but does not set them.