Blossom Hire

Operator


Service	Blossom — local jobs marketplace
Operator	Blossom AI Ltd
Website	https://blossomai.org
Privacy policy	https://blossomai.org/privacypolicy.html
Contact	https://blossomai.org/contact.html
API host	`hello.blossomai.org`

Data handling

This skill collects personal data and sends it to the Blossom API. Be transparent with the user about what is collected.

Data	When collected	Why
Name, surname, email	Registration	Account identity
Mobile number	Registration (optional)	Employer contact
Password (passKey)	Registration	Account authentication
Street, city, postcode, country	Address creation	Job search radius / role location
Job details (headline, description, pay)	Role creation	Published listing

All data is transmitted over HTTPS.
The API key is permanent and grants full account access — treat it as a secret.
No data is stored locally by this skill. All persistence is server-side.

What this skill does

Blossom is a local jobs marketplace. This skill connects to it via a REST API so you can:

Offer work — Post a paid job, task, or shift. Describe what you need, where, when, and how much you'll pay. Real people in the area will see it and can apply.
Find work — Search for jobs near a location, apply to roles that match, and answer any screening questions the employer has set.

Everything goes through a single API with permanent Bearer-key authentication. No sessions, no expiry.

Two account types

Account	`userType`	Purpose
Employer	`employer`	You have work that needs doing. You post roles and review who applies.
Job-seeker	`support`	You're available to work. You search for roles, apply, and get interviewed.

The same six endpoints serve both types. The /ask endpoint adapts its responses based on account type — employers get candidate information, job-seekers get job matches and screening questions.

When to activate

Use this skill when the user wants to:

Offer work (employer): - Post a job, task, or shift - Hire someone or find staff - See who applied / check candidates - Update or remove a listing

Find work (job-seeker): - Search for jobs or shifts nearby - Apply to a role - Answer screening questions from an employer - Check the status of applications

General: - Create a Blossom account - Add or update a location / address

Trigger phrases: "Post a job", "Hire someone", "I need staff", "I need help with…", "Find me work", "Search for jobs near me", "Apply to that role", "Any candidates?", "Update my listing".

API reference

Base URL

https://hello.blossomai.org/api/v1/blossom/protocol

Endpoints

Method	Path	Auth	Purpose
`POST`	`/register`	None	Create account → get API key
`POST`	`/address`	Bearer	Create / update address(es)
`DELETE`	`/address`	Bearer	Soft-delete address(es)
`POST`	`/role`	Bearer	Create / update role(s)
`DELETE`	`/role`	Bearer	Soft-delete role(s)
`POST`	`/ask`	Bearer	Conversational AI endpoint

Session state

Store and reuse across calls: - API_KEY — returned from /register, used as Bearer token for all subsequent calls - PERSON_ID — returned from /register - ADDRESS_ID — returned from /address, needed when creating a role

The API key is permanent. There is no session expiry or login flow.

Important: Never store the API key in global config. Keep it in runtime memory for the current session only.

Conversation flow

Determine the mode

Ask early: "Are you looking to hire, or looking for work?"

Hiring → register as userType: "employer" (optionally with companyName)
Looking for work → register as userType: "support" (must include rightToWork: true)

Collecting information

Gather details conversationally — don't front-load. Ask only for what's missing.

Identity (ask when ready to call the API) - Email, first name, surname - Mobile country code (e.g. +44), mobile number - A passKey (password) they choose

Employer: role details (required to post a job)

Headline — one line
Description — 2–6 lines of what the helper will do
When — working hours, or "flexible"
Where — street, city, postcode, country
Pay — amount + frequency (total | per hour | per week | per month | per year)

Optional extras - Requirements — screening questions (name + mandatory flag) - Benefits — perks (name + mandatory flag)

Job-seeker: location only

Where they are (street, city, postcode, country) — needed for job search radius

Employer step sequence

Collect role details.
Confirm back in one compact summary: headline, when, where, pay.
Collect identity if not already known.
Register (userType: "employer") → store API_KEY and PERSON_ID.
Create address → store ADDRESS_ID.
Create role with the ADDRESS_ID → confirm with role ID.
When asked to check candidates → call /ask.

Job-seeker step sequence

Collect identity and location.
Register (userType: "support", rightToWork: true) → store API_KEY and PERSON_ID.
Create address (their home/base location) → store ADDRESS_ID.
Call /ask to search for nearby jobs: "Find jobs near me" or "What work is available?"
The API returns matching roles. Present them to the user.
To apply: call /ask with "Apply to role <id>" — the API handles the application.
The API may return follow-up screening questions. Relay the questions to the user and send their answers back to /ask.

API contract

1. Register

POST /register — no auth required.

Request:

{
  "name": "<first name>",
  "surname": "<surname>",
  "email": "<email>",
  "userType": "support",
  "passKey": "<password>",
  "rightToWork": true,
  "mobileCountry": "<+44>",
  "mobileNo": "<number>"
}

Field	Required	Notes
`name`	yes
`surname`	yes
`email`	yes	Must be unique
`userType`	yes	`support` (job-seeker) or `employer`
`passKey`	yes	User-chosen password
`rightToWork`	yes*	Must be `true` when `userType` is `support`
`companyName`	no	Required-ish for `employer` type
`mobileCountry`	no	e.g. `+44`
`mobileNo`	no

Success response 201:

{
  "success": true,
  "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "personId": 803
}

If the email already exists the API returns 400 with an error message. Do not retry — inform the user.

2. Create address

POST /address — Bearer auth required.

Request:

{
  "addresses": [
    {
      "id": 0,
      "houseNumber": "<optional>",
      "street": "<street>",
      "area": "<optional>",
      "city": "<city>",
      "country": "<country>",
      "postcode": "<postcode>",
      "label": "Work location",
      "isHome": false,
      "isActive": true
    }
  ]
}

id: 0 creates a new address.
To update an existing address, set id to the address ID.
The response includes the created/updated address with its assigned id — store this as ADDRESS_ID.

3. Delete address

DELETE /address — Bearer auth required.

{
  "addresses": [
    { "id": <addressId> }
  ]
}

Cannot delete an address linked to an active role (returns 409).

4. Create role

POST /role — Bearer auth required.

Request:

{
  "roles": [
    {
      "id": 0,
      "headline": "<headline>",
      "jobDescription": "<description>",
      "introduction": "",
      "workingHours": "<when>",
      "salary": <amount>,
      "currencyName": "GBP",
      "currencySymbol": "£",
      "paymentFrequency": {
        "choices": ["<frequency>"],
        "selectedIndex": 0
      },
      "requirements": [
        { "requirementName": "<name>", "mandatory": false, "originalRequirement": true }
      ],
      "benefits": [
        { "benefitName": "<name>", "mandatory": false }
      ],
      "addressId": <ADDRESS_ID>,
      "isRemote": false,
      "isActive": true,
      "days": 30,
      "maxCrew": 1,
      "modified": <epochMillis>,
      "roleIdentifier": "openclaw-<epochMillis>"
    }
  ]
}

Field	Required	Notes
`id`	yes	`0` to create, existing ID to update
`headline`	yes	Short title
`jobDescription`	yes	Full description
`workingHours`	yes	e.g. `"Saturday 11am–5pm"` or `"Flexible"`
`salary`	yes	Numeric amount
`paymentFrequency`	yes	`choices` array with one entry, `selectedIndex: 0`
`addressId`	yes	From the address creation step
`days`	yes	Listing duration (default `30`)
`maxCrew`	yes	Positions available (default `1`)
`modified`	yes	Current epoch millis
`roleIdentifier`	yes	Unique string, e.g. `"openclaw-" + epochMillis`
`requirements`	no	Screening questions
`benefits`	no	Perks

Success response 201: The role(s) with assigned IDs.

5. Delete role

DELETE /role — Bearer auth required.

{
  "roles": [
    { "id": <roleId> }
  ]
}

Every role id must belong to the authenticated account (returns 403 otherwise).

6. Ask

POST /ask — Bearer auth required.

{
  "instructions": "<natural language>"
}

Send a plain-language message. The API knows the account type and full state — it handles everything and returns a JSON response. Just relay what the user said.

Request examples

Reference curl examples — replace <placeholders> with real values. All authenticated endpoints need the Authorization header.

Environment

API="https://hello.blossomai.org/api/v1/blossom/protocol"
KEY="<apiKey>"
AUTH="Authorization: Bearer $KEY"

Register

curl -sS "$API/register" 
  -H "content-type: application/json" 
  -d '{
    "name": "<name>",
    "surname": "<surname>",
    "email": "<email>",
    "userType": "support",
    "passKey": "<passKey>",
    "rightToWork": true,
    "mobileCountry": "<+44>",
    "mobileNo": "<number>"
  }' | jq .

Create address

curl -sS "$API/address" 
  -H "content-type: application/json" 
  -H "$AUTH" 
  -d '{
    "addresses": [{
      "id": 0,
      "street": "<street>",
      "city": "<city>",
      "country": "<country>",
      "postcode": "<postcode>",
      "label": "Work location",
      "isHome": false,
      "isActive": true
    }]
  }' | jq .

Create role

NOW=$(date +%s000)

curl -sS "$API/role" 
  -H "content-type: application/json" 
  -H "$AUTH" 
  -d '{
    "roles": [{
      "id": 0,
      "headline": "<headline>",
      "jobDescription": "<description>",
      "introduction": "",
      "workingHours": "<when>",
      "salary": <amount>,
      "currencyName": "GBP",
      "currencySymbol": "£",
      "paymentFrequency": { "choices": ["<frequency>"], "selectedIndex": 0 },
      "requirements": [],
      "benefits": [],
      "addressId": <ADDRESS_ID>,
      "isRemote": false,
      "isActive": true,
      "days": 30,
      "maxCrew": 1,
      "modified": '"$NOW"',
      "roleIdentifier": "openclaw-'"$NOW"'"
    }]
  }' | jq .

Delete role

curl -sS -X DELETE "$API/role" 
  -H "content-type: application/json" 
  -H "$AUTH" 
  -d '{ "roles": [{ "id": <roleId> }] }' | jq .

Delete address

curl -sS -X DELETE "$API/address" 
  -H "content-type: application/json" 
  -H "$AUTH" 
  -d '{ "addresses": [{ "id": <addressId> }] }' | jq .

Ask (employer)

curl -sS "$API/ask" 
  -H "content-type: application/json" 
  -H "$AUTH" 
  -d '{ "instructions": "Do I have any candidates?" }' | jq .

Ask (job-seeker — find work)

curl -sS "$API/ask" 
  -H "content-type: application/json" 
  -H "$AUTH" 
  -d '{ "instructions": "Find jobs near me" }' | jq .

Ask (job-seeker — apply)

curl -sS "$API/ask" 
  -H "content-type: application/json" 
  -H "$AUTH" 
  -d '{ "instructions": "Apply to role 1042" }' | jq .

Examples

Example 1 — Employer: post a shift

User: I need café cover this Saturday 11–5 in Sherwood. £12/hour.

Flow: 1. Missing: street, postcode. Ask for them. 2. Confirm: "Café cover — Sat 11am–5pm, Sherwood NG5 1AA — £12/hr. Shall I post it?" 3. Collect identity (email, name, surname, mobile, passKey). 4. POST /register (userType: "employer") → store API_KEY, PERSON_ID. 5. POST /address → store ADDRESS_ID. 6. POST /role → return: "Posted! Role ID 1042."

Example 2 — Employer: check candidates

User: Any candidates yet?

Flow: 1. If API_KEY not stored → ask for identity, register first. 2. POST /ask with "Do I have any candidates?". 3. If empty: "Waiting for responses." 4. Otherwise: display the candidate list as returned.

Example 3 — Employer: update a listing

User: Change the pay to £14/hour on my café role.

Flow: 1. POST /role with the existing role id and updated salary: 14. 2. Confirm: "Updated — café cover now shows £14/hr."

Example 4 — Employer: remove a listing

User: Take down the café role.

Flow: 1. DELETE /role with the role id. 2. Confirm: "Removed."

Example 5 — Job-seeker: find and apply

User: I'm looking for bar work in Nottingham this weekend.

Flow: 1. Collect identity (email, name, surname, mobile, passKey). 2. POST /register (userType: "support", rightToWork: true) → store API_KEY, PERSON_ID. 3. POST /address (their Nottingham location) → store ADDRESS_ID. 4. POST /ask with "Find bar work near me this weekend" → API returns matching roles. 5. Present results: "Found 3 roles near you…" 6. User picks one → POST /ask with "Apply to role 1055" → API confirms application. 7. The API may return screening questions (e.g. "Do you have a personal licence?"). Relay the user's answers back via /ask.

Example 6 — Job-seeker: check application status

User: How are my applications going?

Flow: 1. POST /ask with "What's the status of my applications?". 2. Display the response.

blossom-hire

Installation

Blossom Hire

Operator

Data handling

What this skill does

Two account types

When to activate

API reference

Base URL

Endpoints

Session state

Conversation flow

Determine the mode

Collecting information

Employer: role details (required to post a job)

Job-seeker: location only

Employer step sequence

Job-seeker step sequence

API contract

1. Register

2. Create address

3. Delete address

4. Create role

5. Delete role

6. Ask

Request examples

Environment

Register

Create address

Create role

Delete role

Delete address

Ask (employer)

Ask (job-seeker — find work)

Ask (job-seeker — apply)

Examples

Example 1 — Employer: post a shift

Example 2 — Employer: check candidates

Example 3 — Employer: update a listing

Example 4 — Employer: remove a listing

Example 5 — Job-seeker: find and apply

Example 6 — Job-seeker: check application status