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
| To | Give a workspace token | With the scope |
|---|---|---|
| Read only | any role at the organization that holds your clients | workspace:read |
| Create, rename and close | Deployment Manager or Engineer there | fleet:write |
| Also move organizations between parents | Organization Administrator at the current parent and at the new one | fleet: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
/workspaces/{workspace_id}/organizations Scope: workspace:read
Pass deleted=include.
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?deleted=include" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?deleted=include" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "deleted": "include", },)response.raise_for_status(){ "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
/workspaces/{workspace_id}/organizations Scope: workspace:read
Pass updated_since set to the stored watermark, with deleted=include.
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?updated_since=2026-11-08T09%3A00%3A00Z&deleted=include" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "updated_since": "2026-11-08T09:00:00Z", "deleted": "include", },)response.raise_for_status(){ "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
pathof everything below it, but only the moved organization appears as changed. If you storepath, read the subtree again when you see an organization whoseparent_idchanged, by listing withroot_idset to itsid. Theparent_idof 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:
/workspaces/{workspace_id}/organizations Scope: workspace:read
Filter by psa_client_id, with deleted=include. Add parent_id to look under one part of the tree.
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?psa_client_id=10042&deleted=include" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "psa_client_id": "10042", "deleted": "include", },)response.raise_for_status(){ "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 returns | In the PSA | Do |
|---|---|---|
| Nothing | Active company | Create the organization. |
| One live organization | A different name or RMM id | Update it. |
| One live organization | A different parent | Move it. |
| One live organization | Company closed | Delete it, after its agents. See Offboard a client. |
| One deleted organization | Company active again | Restore it. |
| Two or more | Anything | Stop. 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:
- curl
- PowerShell
- Python
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" }'$body = @{ name = "Pine Ridge Dental" parent_id = "0a9e0000-0000-4000-8000-000000000100" psa_client_id = "10061" rmm_client_id = "PINERIDGE-01"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "Pine Ridge Dental", "parent_id": "0a9e0000-0000-4000-8000-000000000100", "psa_client_id": "10061", "rmm_client_id": "PINERIDGE-01", },)response.raise_for_status(){ "message": "organization created", "id": "0a9e0000-0000-4000-8000-000000000106", "cache_clear_status": "ok"}A new site under a company:
- curl
- PowerShell
- Python
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" }'$body = @{ name = "Finance" parent_id = "0a9e0000-0000-4000-8000-000000000101"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "Finance", "parent_id": "0a9e0000-0000-4000-8000-000000000101", },)response.raise_for_status(){ "message": "organization created", "id": "0a9e0000-0000-4000-8000-000000000102", "cache_clear_status": "ok"}A changed name or client id:
- curl
- PowerShell
- Python
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" }'$body = @{ psa_client_id = "10063"}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000103" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.patch( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000103" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "psa_client_id": "10063", },)response.raise_for_status(){ "message": "organization updated", "id": "0a9e0000-0000-4000-8000-000000000103"}A different parent:
- curl
- PowerShell
- Python
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" }'$body = @{ parent_id = "0a9e0000-0000-4000-8000-000000000103"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000102/move" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000102/move" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "parent_id": "0a9e0000-0000-4000-8000-000000000103", },)response.raise_for_status(){ "message": "organization moved", "cache_clear_status": "ok"}A closed company, then one that came back:
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.delete( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "organization deleted", "cache_clear_status": "ok"}/workspaces/{workspace_id}/organizations/{id}/restore Scope: fleet:write
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104/restore" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104/restore" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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
| Call | Response | Cause and fix |
|---|---|---|
| Update, delete, restore or move | 403 APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION | The organization does not exist, or the token cannot change it. The API returns the same response for both. |
| Delete | 409 APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY | It still has live agents, ingest keys or child organizations. Remove those first. |
| Restore | 409 APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED | Its parent is deleted. Restore the parent first. |
| Move | 400 naming parent_id | The destination is the organization itself, something below it, a deleted organization, or too deep in the tree. |
| Move | 409 APP_API_ERR_CONFLICT | The 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 list | 400 naming cursor | The 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.