> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/how-the-apps-work/screens/staff/org-mapping.md).

# Organization mapping

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). Platforms: web. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/staff/org-mapping.md).
{% endhint %}

A drag-and-drop board on which staff link Snapfix sites to organizations, and organizations to their Stripe, HubSpot and Xero records.

* **Where:** admin app `/organization-mapping`; menu "Organization Mapping".
* **Who:** any signed-in staff user. The route checks only that a session exists. The organization routes take only staff tokens on the server; the site list does not check the staff flag.
* **Feature:** [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md)

## Layout

1. The title "Organization Mapping". At the right: a legend with "Customer", "Churn" and "Connected", which mark customer, churned and linked items; the "Customer type:" select; and "Selected: N" while sites are ticked.
2. Three cards side by side; items are dragged between them. The card titles are internal codes:
   * **"HSX"**: three open panels, "Stripe", "Hubspot" and "Xero", each listing that kind of record by name, 50 at a time with "Load More", under a "Search" box. A record linked to an organization is marked as connected and cannot be dragged; clicking it scrolls to its organization, which is highlighted for a second.
   * **"SFORG"**: one row per organization: the number of linked records, the name, and the number of linked sites; the two numbers have no heading. A "Search" box above, and a "Create" button below the rows. Clicking a row opens [Organization details](#organization-details).
   * **"SFA"**: one row per site, 50 at a time with "Load More", under a "Search" box. Each row has a checkbox, the site name and an info icon. A linked site is marked as connected, cannot be ticked or dragged, and clicking it scrolls to its organization. A deleted site is marked as deleted and cannot be ticked or dragged. Without a customer type the list holds every type and deleted sites too ([`GET /v4/parents`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v4parents)).

The info icon opens a popover: "Name", "Customer Type" ("Uncategorised" when the type is not one of the six), "Created Date", "First Invoice Date" and "Next Renewal Date", as YYYY-MM-dd or "N/A", and "Status" "Deleted" for a deleted site.

## Inputs

| Field               | Type                                                                                              | Required | Default | Rules and messages                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Customer type:      | Select: "All", "Customer", "Sales Trial", "Churn", "Test", "Investor / Pro Bono", "Uncategorised" | No       | "All"   | Reloads the sites column from the first page with that type, and clears the ticked sites.                                                                                        |
| Search (HSX, SFORG) | Text                                                                                              | No       | Empty   | Filters the loaded records or organizations by name, ignoring case, 500 ms after typing. The text is used as a regular expression, so a character such as "(" breaks the filter. |
| Search (SFA)        | Text                                                                                              | No       | Empty   | Searches site names on the server 500 ms after typing, from the first page, and clears the ticked sites.                                                                         |
| Site checkbox       | Checkbox                                                                                          | No       | Off     | Disabled for a linked or deleted site. While sites are ticked, only ticked sites can be dragged.                                                                                 |

## Actions

| Action                                            | Who   | What happens                                                                                                                                                                                                                                                          | API                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the page                                     | Staff | Loads every organization with its links, every record of each kind with no paging, and the first 50 sites.                                                                                                                                                            | [`GET /v1/admin/organizations`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminorganizations), [`GET /v1/admin/organizations/account/{name}`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminorganizationsaccountname) for `stripe`, `hubspot` and `xero`, [`GET /v4/parents`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v4parents) |
| "Load More"                                       | Staff | Records: shows the next 50 of the loaded list. Sites: loads the next 50.                                                                                                                                                                                              | Sites: [`GET /v4/parents`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v4parents)                                                                                                                                                                                                                                                                                                     |
| Drag a site onto an organization                  | Staff | Asks "Confirmation": "Are you wish to connect the to ?", or "… accounts …" when sites are ticked. "Confirm" sends one request for each ticked site, or for the dragged one, clears the ticks, and shows "Success" once all have answered, whether or not they worked. | [`PUT /v1/admin/parents/{uuid}/connect-organization`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminparentsuuidconnect-organization)                                                                                                                                                                                                                                             |
| Drag a record onto an organization                | Staff | When the organization already has a record of that kind, an error box " connection found" says "The organization already connected to ". Otherwise "Confirmation" asks "Are you wish to connect the to ?", and "Confirm" links it and shows "Success".                | [`PUT /v1/admin/organizations/{uuid}/connect-account`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminorganizationsuuidconnect-account)                                                                                                                                                                                                                                           |
| Drag a record onto a site with an organization    | Staff | The same check on the site's organization; its error box says "The account have a connection with the organization, which is already connected to ", and its question "The account have a connection with the organization, are you wish to connect the to ?".        | [`PUT /v1/admin/organizations/{uuid}/connect-account`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminorganizationsuuidconnect-account)                                                                                                                                                                                                                                           |
| Drag a record onto a site without an organization | Staff | Opens [Create connection](#create-connection).                                                                                                                                                                                                                        | See the dialog                                                                                                                                                                                                                                                                                                                                                                                            |
| "Create"                                          | Staff | Opens [Create Organization](#create-organization).                                                                                                                                                                                                                    | See the dialog                                                                                                                                                                                                                                                                                                                                                                                            |

Other drags, such as a site onto a record, do nothing. The dialog texts put the site, record and organization names into HTML. Failed changes show the server's message.

## States

* **Loading:** each card shows a spinner until its list arrives; each record panel spins on its own.
* **Empty:** a card or panel with no rows shows an empty placeholder.
* **Error:** the lists show no error message. A failed organization or site list leaves its card empty. A record list that fails as a request leaves its panel empty; one whose answer is not a success leaves the panel spinning.
* **No permission:** none in the app.

## Dialogs and sheets

### Create connection

"Create connection", 400 px wide. The text "Are you which to connect to ?", then "Organization is required to create a connection."

| Field             | Type | Required | Default           | Rules and messages                    |
| ----------------- | ---- | -------- | ----------------- | ------------------------------------- |
| Organization name | Text | Yes      | The record's name | "Save" is disabled while it is blank. |

| Action   | Who   | What happens                                                                                                                                                                                                                                                                                                                                                       | API                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Save"   | Staff | Creates the organization, which joins the list at once, then links the site to it, then links the record, and closes with "Success". When a link step gets an answer that is not a success, the dialog keeps its spinner and the steps after it do not run; when a step fails as a request, the next step runs anyway, so an organization can be left half linked. | [`POST /v1/admin/organizations`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminorganizations), [`PUT /v1/admin/parents/{uuid}/connect-organization`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminparentsuuidconnect-organization), [`PUT /v1/admin/organizations/{uuid}/connect-account`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminorganizationsuuidconnect-account) |
| "Cancel" | Staff | Closes. Disabled once "Save" has been pressed.                                                                                                                                                                                                                                                                                                                     | None                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### Create Organization

"Create Organization", 400 px wide, with the required "Organization name"; "Save" is disabled while it is blank. On success "Success" shows, the dialog closes and the organization joins the list. After a refused save, "Save" keeps its spinner and "Cancel" stays disabled, so only the corner close button works. Uses [`POST /v1/admin/organizations`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminorganizations).

### Organization details

"Organization details", 800 px wide. A spinner shows until the details load; a request that fails closes the dialog.

* The name, with an "Edit" button. Editing shows "Organization name" with a save button, disabled while the name is blank or unchanged, and a close button.
* An "HSX" card: each linked record with its kind ("Stripe", "Hubspot" or "Xero") and a delete button.
* An "SFA" card: each linked site with a delete button.
* Footer: "Delete" (danger) and "Close".

| Action               | Who   | What happens                                                                                                                                                                                                                                                                                                                                                                 | API                                                                                                                                                                   |
| -------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open                 | Staff | Loads the organization and its links.                                                                                                                                                                                                                                                                                                                                        | [`GET /v1/admin/organizations/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminorganizationsuuid)                                      |
| Save the name        | Staff | Renames the organization here and in the list, with "Success".                                                                                                                                                                                                                                                                                                               | [`PUT /v1/admin/organizations/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminorganizationsuuid)                                      |
| Delete a record link | Staff | "Confirmation": "Are you sure you wish to delete the to connection?"; "Confirm" unlinks it, with "Success".                                                                                                                                                                                                                                                                  | [`PUT /v1/admin/organizations/{uuid}/disconnect-account`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminorganizationsuuiddisconnect-account) |
| Delete a site link   | Staff | The same question for the site; "Confirm" unlinks it, with "Success".                                                                                                                                                                                                                                                                                                        | [`PUT /v1/admin/parents/{uuid}/disconnect-organization`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminparentsuuiddisconnect-organization)   |
| "Delete"             | Staff | "Delete organization": "Are you sure you wish to delete the organization?" with a danger "Delete". On success the dialog closes and the organization leaves the list. The server unlinks every site of the organization and soft-deletes it; its Stripe, HubSpot and Xero links are fields of the organization, so those records are not changed and show as unlinked again. | [`DELETE /v1/admin/organizations/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#delete-v1adminorganizationsuuid)                                |
| "Close"              | Staff | Closes.                                                                                                                                                                                                                                                                                                                                                                      | None                                                                                                                                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/how-the-apps-work/screens/staff/org-mapping.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
