# 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](https://sparklogs.com/docs/api/reference/access.md).

## Read the current organizations

### First run: load everything

**`GET /workspaces/{workspace_id}/organizations`** [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

Pass `deleted=include`.

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/paging-and-sync.md) for each of these.

### Every later run: load what changed

**`GET /workspaces/{workspace_id}/organizations`** [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

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

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

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

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/use-cases/onboard-client.md) 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](https://sparklogs.com/docs/api/reference/organizations.md#create-organization). |
| One live organization | A different name or RMM id | [Update it](https://sparklogs.com/docs/api/reference/organizations.md#update-organization). |
| One live organization | A different parent | [Move it](https://sparklogs.com/docs/api/reference/organizations.md#move-organization). |
| One live organization | Company closed | [Delete it](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization), after its agents. See [Offboard a client](https://sparklogs.com/docs/api/use-cases/offboard-client.md). |
| One deleted organization | Company active again | [Restore it](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization). |
| 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](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id).
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](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "message": "organization updated",
  "id": "0a9e0000-0000-4000-8000-000000000103"
}
```

A different parent:

**`POST /workspaces/{workspace_id}/organizations/{id}/move`** [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "message": "organization moved",
  "cache_clear_status": "ok"
}
```

A closed company, then one that came back:

**`DELETE /workspaces/{workspace_id}/organizations/{id}`** [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "message": "organization deleted",
  "cache_clear_status": "ok"
}
```

**`POST /workspaces/{workspace_id}/organizations/{id}/restore`** [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "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.

---

Source: <https://sparklogs.com/docs/api/use-cases/sync-organizations>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
