Email to note
Turn an approved email into a linked note
Summarize a customer thread, resolve the customer, ask for confirmation, and write the approved summary as a note.
GET /search -> confirm -> POST /notes
ShelfCycle Developer API
Resolve records and write context back to ShelfCycle.
A scoped API for approved local workflows. Search returns typed candidates, a person confirms the record, then the workflow writes a note or contact with an idempotency key and gets a ShelfCycle link back.
Human-approved writesSafe retriesLive user permissionsAudit trail
curl "$SHELFCYCLE_API_BASE_URL/search?q=Northstar&types=customer,contact" \
-H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
-H "X-ShelfCycle-Client: Email notes automation"
{
"data": [
{
"type": "contact",
"id": "contact-id",
"displayName": "Jordan Buyer",
"subtitle": "Northstar Chemical | jordan@example.com | President",
"url": "https://app.shelfcycle.com/org-northstar/customers/customer-id/contacts",
"matchedFields": [
{ "field": "email", "label": "Email", "value": "jordan@example.com" }
]
}
],
"meta": {
"rankingIsContractual": false,
"truncated": false
}
}Core workflow
Resolve, confirm, write.
Every write follows the same loop. The API resolves candidate records, a person confirms the exact target, and the workflow writes approved context back to ShelfCycle.
01 Resolve
Search returns candidates
The caller uses GET /search and receives typed cards with record identity, a subtitle, matched fields, and a URL.
02 Confirm
A person approves the match
The supervising user confirms the exact type and id. Nothing is written until the target is approved.
03 Write
Write back, get a link
The caller creates a note or contact with a stable idempotency key. ShelfCycle returns the created record and URL.
In: approved email | call notes | business card | pasted textOut: a note or contact linked in ShelfCycle
Use cases
Write relationship context back to the system of record.
The v1 surface is intentionally narrow. It supports search, approved notes, and approved contacts. It does not write orders, inventory, pricing, costs, or accounting records.
Signature to contact
Capture a contact from an email signature
Extract a name, title, email, and phone, resolve the parent customer or supplier, and create the contact under it.
GET /search -> confirm -> POST /contacts
Call to note
Attach pasted call notes to the right record
Resolve the customer, supplier, or product from pasted call notes and post the approved note with the time it happened.
GET /search -> confirm -> POST /notes
Resolve first
Resolve a customer before any write
Use ShelfCycle search as the resolution surface instead of rebuilding matching logic against exported data.
GET /search -> { type, id }
Built for agents
Designed for coding agents and the people supervising them.
The API follows the way local agents operate: inspect current capability, resolve before acting, branch on typed errors, retry safely, and return a human-verifiable URL.
Search returns typed candidates
One endpoint returns candidate cards with type, id, subtitle, URL, and matched fields. A caller can show evidence before asking a person to confirm.
Errors are machine-readable
Every failure uses the same envelope with a stable code. Callers can branch on missing_scope, stale_record, and idempotency_key_reused.
/me describes the key
A scope-free request confirms the org, key preview, scopes, and acting user before the workflow takes any other action.
Safety and governance
Governed access, not a side door.
Every write is attributed to a real user and checked against current permissions for that user. Keys are scoped, revocable, rate-limited, and tenant-bound.
Least-privilege scopes
Keys carry explicit capabilities. A search:read key cannot write notes or contacts.
Writes act as a real user
Each key is issued to a ShelfCycle user. The API checks that user's live permissions on every call.
Idempotent writes
POST requests require Idempotency-Key. The same key and body returns the original record instead of creating a duplicate.
Optimistic concurrency
PATCH requests use If-Match with the latest updatedAt. A stale value returns 409 stale_record.
Tenant isolation
The org comes from the authenticated key. Requests cannot select or override another tenant.
Audit trail
Responses include a request id, and writes are attributed through the key and acting user.
Quickstart
Verify a key, run a search, and write one approved note.
Start with GET /me, resolve a candidate with GET /search, then create a note with POST /notes and a stable Idempotency-Key.