borkoldocs

Contacts

Registration and sessions

Register a contact account, log in for a session token, and log out.

View as Markdown

These three endpoints manage contact accounts and session tokens. register and login return a token alongside the contact; send it as X-Customer-Token on contact-authenticated endpoints. All three require the contacts:write scope on your API key (customers:write accepted).

POST /v1/api/contacts/register

Also served at /v1/api/customers/register for existing integrations; identical request and response.

Register a storefront contact account. Returns the created contact plus a session token. If the email already belongs to a guest row (created by cart email capture in the Commerce module), the guest is upgraded in place: same id, order history preserved, name and password set from this request. Only an email that belongs to a real (non-guest) account is rejected. Extra rate limit: 10 requests per minute per IP.

Body parameters

NameTypeRequiredDescription
namestringYesFull name. Maximum 150 characters.
emailstringYesValid email address, maximum 255 characters. Lowercased server-side. Must not belong to an existing non-guest account.
passwordstringYesMinimum 8 characters.
Request
curl -X POST https://api.borkol.com/v1/api/contacts/register \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com","password":"s3cret-pass"}'
Request (JS)
const res = await fetch("https://api.borkol.com/v1/api/contacts/register", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    email: "jane@example.com",
    password: "s3cret-pass",
  }),
});
const { data: contact, token } = await res.json();

Status: 201 Created.

Response
{
  "data": {
    "id": "9d4e2f1a-6b3c-4f8e-9a1d-2c5b7e8f0a3d",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": null,
    "kind": "person",
    "company_name": null,
    "registration_number": null,
    "vat_id": null,
    "external_id": null,
    "display_name": "Jane Doe",
    "created_at": "2026-08-14T10:32:11+00:00"
  },
  "token": "12|Fq8sT3vY6wZx9aBcDeFgHiJkLmNoPqRsTuVwXyZ0"
}

Errors

  • 422 with errors.email ["Email already registered."] when a non-guest account already uses the email.
  • 422 for field validation failures (missing name, invalid email, password shorter than 8 characters).
  • 429 when the 10 requests per minute per IP limit is exceeded.

POST /v1/api/contacts/login

Also served at /v1/api/customers/login for existing integrations; identical request and response.

Authenticate a contact with email and password. Returns the contact and a fresh session token, and updates the account's last_login_at. The check is timing-safe and never reveals whether the email exists: a wrong password, an unknown email, and a guest account (which has no password) all fail with the same 422. Extra rate limit: 10 requests per minute per IP.

Body parameters

NameTypeRequiredDescription
emailstringYesValid email address. Lowercased server-side before lookup.
passwordstringYesThe account password.
Request
curl -X POST https://api.borkol.com/v1/api/contacts/login \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","password":"s3cret-pass"}'

Status: 200 OK.

Response
{
  "data": {
    "id": "9d4e2f1a-6b3c-4f8e-9a1d-2c5b7e8f0a3d",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+31612345678",
    "kind": "person",
    "company_name": null,
    "registration_number": null,
    "vat_id": null,
    "external_id": null,
    "display_name": "Jane Doe",
    "created_at": "2026-08-14T10:32:11+00:00"
  },
  "token": "13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"
}

Errors

  • 422 with errors.email ["Invalid credentials."] for a wrong email or a wrong password. The error is always on the email key.
  • 429 when the 10 requests per minute per IP limit is exceeded.

POST /v1/api/contacts/logout

Also served at /v1/api/customers/logout for existing integrations; identical request and response.

Revoke the contact session token given in X-Customer-Token. The header must be present and valid to pass contact authentication: a currently valid token is revoked and the request returns 204, while an already-revoked or unknown token fails authentication with 401 {"message": "Invalid customer token."}.

Headers

NameTypeRequiredDescription
X-Customer-TokenstringYesThe session token to revoke.

No body.

Request
curl -X POST https://api.borkol.com/v1/api/contacts/logout \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

Status: 204 No Content. The response has no body.

Errors

  • 401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.