Blossom Hire

Operator

Data handling

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

• 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

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".

Tools

Use bash with curl and jq.

Base URL

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

Endpoints

Requirements

• bash tool access
• curl and jq installed

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)

1. Headline — one line
2. Description — 2–6 lines of what the helper will do
3. When — working hours, or "flexible"
4. Where — street, city, postcode, country
5. 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

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

Job-seeker step sequence

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

Output rules

• Never promise that someone will apply (employer) or that they'll get hired (job-seeker).
• If zero candidates/jobs: say "Waiting for responses." or "No matching jobs found right now."
• Don't infer suitability beyond what the API returns.

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>"
}

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>"
    }
  ]
}

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 question or statement>"
}

A conversational endpoint. Send natural language and receive actionable JSON. The API sees the full account state (roles, addresses, applications) and responds accordingly.

Behaviour varies by account type:

Example instructions:

Employer:

• "Do I have any candidates?"
• "Show me who applied to the café role"
• "How many applications this week?"

Job-seeker:

• "Find jobs near me"
• "What work is available in Nottingham?"
• "Apply to role 1042"
• "I have a food hygiene certificate" (answering a screening question)
• "What's the status of my applications?"

Bash templates

Replace <placeholders> before running. 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.