> 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/product/features/integrations/vendor-api.md).

# Vendor API

{% 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)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/vendor-api.md).
{% endhint %}

The **vendor API** lets a partner system work with one **site** through a **vendor key**, an [Open API](https://docs.snapfix.com/product/features/integrations/open-api.md) key with the vendor flag set. With it, the partner system reads the site's **areas**, **rooms**, **groups** with their tags, **asset registers** and **assets**, reads, creates, changes and deletes **tasks**, and uploads files. Tasks made through it carry origin 11, `XVENDOR`, which the origin table does not name, and Snapfix's housekeeping counts treat them as D3X tasks. Nothing in the repos calls these routes, but the staging data holds 45 vendor keys and recent tasks with origin 11, so partners use it.

## Rules

### Keys

* Staff create a vendor key as an Open API key with the vendor flag set; the flag is off by default (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/Admin/PublicSimpleAPIController.php:35`, `:53`). How partners get keys is open \[[ASK-159](https://github.com/snapfix/docs/blob/main/ASK.md#ask-159-how-do-customers-and-vendors-get-api-keys)].
* A key without the flag is refused with `401` and "It looks like you don't have an active subscription. Upgrade your plan to get started." (`app/Http/Middleware/AuthorizeXVendorApi.php:44-46`, `lang/en/messages.php:205`).
* Otherwise the key rules are the Open API's ([Open API: keys](https://docs.snapfix.com/product/features/integrations/open-api.md#keys)): one site per key, the `X-API-Key` header, and no way to revoke a key in the product. A vendor key also passes the Open API routes \[[ASK-160](https://github.com/snapfix/docs/blob/main/ASK.md#ask-160-should-a-vendor-key-also-open-the-open-api)].
* The vendor API has its own documentation page, at `/api/documentation/xvendor` (`app/Http/Middleware/AuthBasic.php:47-53`).

### Reads

* Areas and rooms show only their ID and name, and come from one building of the site, the first one found, so a site with several buildings shows one building's rooms and areas \[[ASK-162](https://github.com/snapfix/docs/blob/main/ASK.md#ask-162-should-the-vendor-api-return-the-rooms-and-areas-of-every-building-of-a-site)] (`app/Services/BuildingService.php:61-65`).
* Groups are listed and read one at a time; a group read lists its statuses and the names of its members. A group's tag folders are read on their own route.
* Asset registers are listed and read with their ID and name. Assets are listed for one register, named in the required `assetReg` value; an asset shows its ID and title.
* Tasks are listed for one group. A task read includes its room, area, assets, tags, checklist items and chat, and its assignees with names when the read is detailed.

### Creating tasks

* A new task needs a title, and an image or a large title. It needs a group too, unless the site has AI suggestions on; then AI picks the group, and the create fails when it finds none ([Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md)). For sites listed in the AI service's settings, AI picks only among groups named "Housekeeping Guest Requests" and "Reactive Maintenance", the defaults (aitask\_pyserver @ 877304ec49, `app/services/ai_task_group_llm.py:26-27`, `:186-187`). The key is sent to the AI service on those calls, which does not use it.
* A create can also take a description, a colour, one room, one area, asset IDs, tag IDs, assignee IDs, checklist items and chat messages (`app/Http/Requests/v1/XVendor/Job/CreateAssetJobRequest.php`).
* A tag is linked only when its tag folder belongs to the task's group; other tags are skipped. Assignees must be active members of the group.
* A room, area, asset, tag or assignee that cannot be found or used does not stop the create; the answer lists it under `warnings`.
* The create links a room, area or asset of another site when it is given its ID.
* A created task carries origin 11 (`app/Enums/EnumOrigin.php:18`; `app/Http/Controllers/v1/Versions/v1_0/XVendor/JobController.php:268`). php-apis's room task counts count origin 11 as D3X tasks (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/housekeeping.functions.php:853-858`).
* With AI suggestions on, AI can add tags, assignees, a room and an area after the create, filling only what the partner left empty ([Open API](https://docs.snapfix.com/product/features/integrations/open-api.md#creating-changing-and-deleting-tasks)).

### Changing and deleting tasks

* A change can set the title, the image, the large title, the description, the colour and the priority; set one room or one area; and add or remove tags, assignees and assets (`app/Http/Requests/v1/XVendor/Job/UpdateAssetJobRequest.php:22-45`).
* A change refuses a room or area of another site and lists it as a warning, but still links an asset of another site. Assignees added must be active members of the group.
* Deleting a task is a soft delete, and uploads work as for the Open API.

### Limits

* The vendor routes have the Open API's limits: 50,000 calls a day and 60 a minute by default ([Open API: uploads and limits](https://docs.snapfix.com/product/features/integrations/open-api.md#uploads-and-limits); `app/Providers/RouteServiceProvider.php:72-80`).
* No plan or subscription check applies to these routes.

## Flow

```mermaid
flowchart TD
  call["Partner system sends the vendor key"] --> valid{"Key valid?"}
  valid -- "no" --> e401["401"]
  valid -- "yes" --> flag{"Vendor flag on?"}
  flag -- "no" --> sub["401 with the subscription message"]
  flag -- "yes" --> site{"Group, register or task in the key's site?"}
  site -- "no" --> notfound["Not found"]
  site -- "yes" --> kind{"Read or write?"}
  kind -- "read" --> read["Areas, rooms, groups, registers, assets or tasks"]
  kind -- "write" --> done["Task created, changed or deleted; IDs that fail listed as warnings"]
  done --> origin["New tasks get origin 11"]
```

## Platforms

| Capability          | Web                                                                                                                                                   | iOS | Android |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------- |
| Create a vendor key | No screen; staff call an admin route \[[ASK-159](https://github.com/snapfix/docs/blob/main/ASK.md#ask-159-how-do-customers-and-vendors-get-api-keys)] | No  | No      |
| Use the API         | Partner systems only                                                                                                                                  | No  | No      |

## Screens

* None. No screen shows vendor keys.

## API and data

* [Open API](https://docs.snapfix.com/engineering-reference/api/open-api.md): lists the vendor routes under `/v1/xvendor`. Every row there is marked "(no caller)" and has no section, so no endpoint is linked from this page.
* Tables: [`tPri_Api_Simple_SecretKey`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_api_simple_secretkey.md) (the vendor flag, `fXVendor`), [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (tasks and their origin), [`enum_Origin`](https://docs.snapfix.com/engineering-reference/db/tables/enum_origin.md) (the origin names, which stop before 11), and the task links [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md), [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md) (assets), [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md) and [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md).

## Depends on

* [Open API](https://docs.snapfix.com/product/features/integrations/open-api.md): the same keys, rules and limits.
* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md): the rules API tasks follow.
* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md), [Asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md) and [Asset tasks](https://docs.snapfix.com/product/features/assets/asset-tasks.md): the rooms, areas, registers and assets read and linked.
* [Site tags](https://docs.snapfix.com/product/features/console/site-tags.md), [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the tags, groups and members a create can use.
* [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md): the AI group choice and the fill-in after a create.
* [Guest communications](https://docs.snapfix.com/product/features/integrations/guest-communications.md): Snapfix's housekeeping counts treat origin-11 tasks as D3X tasks, and the D3X webhook creates no tasks itself \[[ASK-14](https://github.com/snapfix/docs/blob/main/ASK.md#ask-14-does-d3x-create-tasks-in-snapfix-today)].

## Edge cases

* **Key without the vendor flag:** `401` with the subscription message.
* **Unknown IDs:** the task is still created or changed, and the IDs come back under `warnings`.
* **Room, area or asset of another site:** linked on create, and an asset also on change.
* **Tags outside the group's tag folders:** skipped.
* **AI cannot place the task:** the create fails.
* **Site with several buildings:** the area and room lists show one building \[[ASK-162](https://github.com/snapfix/docs/blob/main/ASK.md#ask-162-should-the-vendor-api-return-the-rooms-and-areas-of-every-building-of-a-site)].
* **Origin 11:** the task's origin has no name in the origin table.
* **Time zones:** 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/product/features/integrations/vendor-api.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.
