REST API reference

The-Y CRM's public REST API is meant for server-to-server integrations: create/read/update contacts and receive events via webhook. Requests are authenticated with an API key.

Base URL (hosted): https://crm.the-y.at/api/ext/v1 · self-host: https://<your-domain>/api/ext/v1 · Paid feature

Authentication

Every request needs your API key in the header — either as a Bearer token or as X-API-Key:

Authorization: Bearer <YOUR_API_KEY>
# or
X-API-Key: <YOUR_API_KEY>

Create a key: in the app under Settings → 🔌 Integrations → "API keys" → new key. The key is shown only once — store it safely (The-Y only stores a hash). The key is bound to your tenant.

Conventions

• Format: requests & responses in application/json (UTF-8).
• Pagination: lists accept ?limit= (default/max capped server-side) and ?offset=; the response includes hasMore.
• Rate limit: requests are capped per key/minute; on exceeding you get 429 Too Many Requests — retry with backoff.
• Errors: as JSON { "error": { "code": "..." } } with the matching HTTP status.

Contacts

GET/contacts

List contacts (paginated). Optional search via ?q=.

# Request
curl "https://crm.the-y.at/api/ext/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer $API_KEY"

# Response
{
  "data": [
    { "id": "c_123", "name": "Maria Muster", "email": "maria@example.com", "phone": "+4366012345678", "company": "ACME" }
  ],
  "hasMore": false
}

POST/contacts

Create a contact. At least a name or an email is required.

curl -X POST "https://crm.the-y.at/api/ext/v1/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Maria Muster", "email": "maria@example.com", "phone": "+4366012345678", "company": "ACME" }'

# 201 Created
{ "data": { "id": "c_123", "name": "Maria Muster", "email": "maria@example.com" } }

GET/contacts/{id}

Read a single contact.

curl "https://crm.the-y.at/api/ext/v1/contacts/c_123" \
  -H "Authorization: Bearer $API_KEY"

PATCH/contacts/{id}

Partially update a contact — only the sent fields change (existing ones are kept).

curl -X PATCH "https://crm.the-y.at/api/ext/v1/contacts/c_123" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+4366099999999" }'

Outbound webhooks (events)

Instead of polling, have events pushed to your URL. Under Settings → 🔌 Integrations → "Webhooks" you set a target URL, a secret and the events (e.g. contact.created, contact.updated).

• The-Y sends a POST with a JSON payload to your URL.
• Signature: the header X-Signature contains an HMAC-SHA256 over the raw body with your secret. Verify it to check authenticity.
• Delivery is best-effort with retries; your endpoint should return 2xx.

# Verify the signature (Node.js)
const crypto = require("crypto");
const expected = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
if (expected !== req.headers["x-signature"]) return res.status(401).end();

Inbound webhooks

External systems can create/update data in The-Y via a token URL: POST /api/hooks/<token> (token created in Integrations). Per webhook you choose the access level: upsert (create/update only, deletions ignored — anti-lock-in) or full (incl. delete).

What's next