Crm

Customer relationships: the deals of an entity's pipeline (opportunities with a customer or a prospect, their stages and probability), the timeline of calls, meetings, notes and tasks, the pipeline by stage, and the sales reports: the pipeline by owner and month, the win rate, each person's activity, quotas and the forecast; the people at customers and vendors (contacts, erased on request) and the organization's own fields on companies, contacts and deals. Nothing here posts.

POST /forms/leads/{key}

Send a lead from a website

No credential: the key names the form. Whoever fills in the form becomes a lead of the form's company (status new, source web_form, owned by the form's owner). Limited per client address and per form (429 with Retry-After).

Parameters

Request body

application/json (optional): object

application/x-www-form-urlencoded (optional): object

Example request

curl -X POST "$ERP_URL/forms/leads/lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Eva",
  "last_name": "Beispiel",
  "email": "eva@beispiel.example",
  "company": "Beispiel GmbH",
  "message": "Please send us a quote for 25 seats."
}'

Responses

Example response (shape)

{
  "received": true
}

GET /v1/activities

List activities

The timeline of a deal, a lead or a customer, or the open tasks: the newest first (open tasks: the earliest due first). Someone who sees only their own or their team's records gets the activities of those people, the tasks assigned to them and the timelines of the deals, leads and customers they see. Read-only.

Parameters

Example request

curl "$ERP_URL/v1/activities" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "body": "25 users, budget approved for Q1",
    "created_at": "2026-10-04T08:10:00Z",
    "created_by": {
      "id": "user:alice",
      "name": "Alice",
      "type": "human"
    },
    "entity": "CH01",
    "id": "4a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
    "kind": "call",
    "occurred_on": "2026-10-04",
    "opportunity_id": "3f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
    "opportunity_number": "OPP-000001",
    "overdue": false,
    "subject": "Discovery call"
  }
]

POST /v1/activities

Record an activity

A note, call, meeting or e-mail about a deal (opportunity_id) or a customer (entity and party), or a task with its due day and assignee (by default the deal's owner). An activity is never edited or deleted; a task is completed once (POST /v1/activities/{activity_id}/complete). Needs an Idempotency-Key.

Request body

application/json (required): ActivityInput

Example request

curl -X POST "$ERP_URL/v1/activities" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "25 users, budget approved for Q1",
  "kind": "call",
  "occurred_on": "2026-10-04",
  "opportunity_id": "3f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
  "subject": "Discovery call"
}'

Responses

Example response (shape)

{
  "body": "25 users, budget approved for Q1",
  "created_at": "2026-10-04T08:10:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "entity": "CH01",
  "id": "4a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
  "kind": "call",
  "occurred_on": "2026-10-04",
  "opportunity_id": "3f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
  "opportunity_number": "OPP-000001",
  "overdue": false,
  "subject": "Discovery call"
}

POST /v1/activities/{activity_id}/complete

Mark a task done

Record that a task is done, by whom and when. 409 for an activity that is not a task or a task already done; 404 when it does not exist.

Parameters

Example request

curl -X POST "$ERP_URL/v1/activities/4a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d/complete" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "body": "25 users, budget approved for Q1",
  "created_at": "2026-10-04T08:10:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "entity": "CH01",
  "id": "4a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
  "kind": "call",
  "occurred_on": "2026-10-04",
  "opportunity_id": "3f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
  "opportunity_number": "OPP-000001",
  "overdue": false,
  "subject": "Discovery call"
}

GET /v1/contacts

List contacts

The people at customers and vendors, by last and first name. Someone who sees only their own or their team's records gets the contacts of those people and of the customers they see (and every vendor's). Read-only.

Parameters

Example request

curl "$ERP_URL/v1/contacts" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "created_at": "2026-10-23T08:00:00Z",
    "created_by": {
      "id": "user:alice",
      "name": "Alice",
      "type": "human"
    },
    "custom": {},
    "email": "anna.muster@kunde.example",
    "email_opt_out": false,
    "entity": "CH01",
    "erased": false,
    "first_name": "Anna",
    "id": "5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
    "language": "de",
    "last_name": "Muster",
    "name": "Anna Muster",
    "party_code": "C-CH",
    "party_id": "6c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
    "party_kind": "customer",
    "party_name": "Kunde AG",
    "phone": "+41 44 123 45 67",
    "role": "Head of purchasing"
  }
]

POST /v1/contacts

Add a contact

A person at a customer or vendor (party): name, role, e-mail, phones, the language to write to them in, whether they want sales e-mails, and the organization's own contact fields (custom). An agent may add one. 404 for an unknown company or party; 422 for a field that is not one of the organization's or a value of the wrong type. Needs an Idempotency-Key.

Request body

application/json (required): ContactInput

Example request

curl -X POST "$ERP_URL/v1/contacts" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "anna.muster@kunde.example",
  "entity": "CH01",
  "first_name": "Anna",
  "language": "de",
  "last_name": "Muster",
  "party": "C-CH",
  "phone": "+41 44 123 45 67",
  "role": "Head of purchasing"
}'

Responses

Example response (shape)

{
  "created_at": "2026-10-23T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "custom": {},
  "email": "anna.muster@kunde.example",
  "email_opt_out": false,
  "entity": "CH01",
  "erased": false,
  "first_name": "Anna",
  "id": "5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "language": "de",
  "last_name": "Muster",
  "name": "Anna Muster",
  "party_code": "C-CH",
  "party_id": "6c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "party_kind": "customer",
  "party_name": "Kunde AG",
  "phone": "+41 44 123 45 67",
  "role": "Head of purchasing"
}

GET /v1/contacts/{contact_id}

Get a contact

One contact; an erased one shows only that it existed.

Parameters

Example request

curl "$ERP_URL/v1/contacts/5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "created_at": "2026-10-23T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "custom": {},
  "email": "anna.muster@kunde.example",
  "email_opt_out": false,
  "entity": "CH01",
  "erased": false,
  "first_name": "Anna",
  "id": "5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "language": "de",
  "last_name": "Muster",
  "name": "Anna Muster",
  "party_code": "C-CH",
  "party_id": "6c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "party_kind": "customer",
  "party_name": "Kunde AG",
  "phone": "+41 44 123 45 67",
  "role": "Head of purchasing"
}

PATCH /v1/contacts/{contact_id}

Change a contact

Change what the request names ("" clears a text field but the last name; custom changes only the keys sent). A contact never moves to another customer or vendor. The audit trail records which fields changed, never their values. 409 contact_erased for an erased one.

Parameters

Request body

application/json (required): ContactUpdate

Example request

curl -X PATCH "$ERP_URL/v1/contacts/5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "anna@kunde.example",
  "role": "CFO"
}'

Responses

Example response (shape)

{
  "created_at": "2026-10-23T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "custom": {},
  "email": "anna.muster@kunde.example",
  "email_opt_out": false,
  "entity": "CH01",
  "erased": false,
  "first_name": "Anna",
  "id": "5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "language": "de",
  "last_name": "Muster",
  "name": "Anna Muster",
  "party_code": "C-CH",
  "party_id": "6c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "party_kind": "customer",
  "party_name": "Kunde AG",
  "phone": "+41 44 123 45 67",
  "role": "Head of purchasing"
}

POST /v1/contacts/{contact_id}/erase

Erase a contact's personal data

Empty the contact's name, role, e-mail, phones, and own fields for good (the person asked to be forgotten, or the relationship ended). The row stays, so that the deals and activities that named it still say someone was there; it cannot be undone. A person's decision: 403 contact_erase_agent for an agent. 409 contact_erased if already erased.

Parameters

Example request

curl -X POST "$ERP_URL/v1/contacts/5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e/erase" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "created_at": "2026-10-23T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "custom": {},
  "email": "anna.muster@kunde.example",
  "email_opt_out": false,
  "entity": "CH01",
  "erased": false,
  "first_name": "Anna",
  "id": "5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "language": "de",
  "last_name": "Muster",
  "name": "Anna Muster",
  "party_code": "C-CH",
  "party_id": "6c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "party_kind": "customer",
  "party_name": "Kunde AG",
  "phone": "+41 44 123 45 67",
  "role": "Head of purchasing"
}

POST /v1/contacts/{contact_id}/merge

Merge a duplicate contact

Merge this contact, entered twice, into into, another contact of the same customer or vendor (ADR-0089): what the one that stays has no value for (first name, role, e-mail, phones, language, own fields) comes from this one, a "no sales e-mails" wish stays, its deals and activities move, and this one is erased (merged_into_id says where it went). Returns the contact that stays. A person's decision: 403 merge_agent for an agent. 422 contact_merge_other_party for a contact of another customer or vendor, or itself; 409 contact_erased if either was erased.

Parameters

Request body

application/json (required): ContactMerge

Example request

curl -X POST "$ERP_URL/v1/contacts/5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e/merge" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "into": "5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e"
}'

Responses

Example response (shape)

{
  "created_at": "2026-10-23T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "custom": {},
  "email": "anna.muster@kunde.example",
  "email_opt_out": false,
  "entity": "CH01",
  "erased": false,
  "first_name": "Anna",
  "id": "5b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "language": "de",
  "last_name": "Muster",
  "name": "Anna Muster",
  "party_code": "C-CH",
  "party_id": "6c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "party_kind": "customer",
  "party_name": "Kunde AG",
  "phone": "+41 44 123 45 67",
  "role": "Head of purchasing"
}

GET /v1/custom-fields

List the organization's own fields

The fields the organization added to its companies (customers and vendors), contacts and deals, in their order. A record's values are in its custom, by the field's key.

Parameters

Example request

curl "$ERP_URL/v1/custom-fields" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "record": "company",
    "key": "string",
    "label": "string",
    "type": "choice",
    "choices": [
      "string"
    ],
    "position": 1,
    "retired": true
  }
]

POST /v1/custom-fields

Add a field of the organization's own

A field on every company, contact or deal: text, number, date, yes_no or choice (with its choices). Its key and type never change. Up to 25 in use per kind of record (409 custom_fields_full); 409 custom_field_exists for a key in use. Needs an Idempotency-Key.

Request body

application/json (required): CustomFieldInput

Example request

curl -X POST "$ERP_URL/v1/custom-fields" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "choices": [
    "Retail",
    "Manufacturing",
    "Services"
  ],
  "key": "industry",
  "label": "Industry",
  "record": "company",
  "type": "choice"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "record": "company",
  "key": "string",
  "label": "string",
  "type": "choice",
  "choices": [
    "string"
  ],
  "position": 1,
  "retired": true
}

PATCH /v1/custom-fields/{field_id}

Change or retire a field of the organization's own

A new label, position or choices (a choice a record holds stays: 409 custom_field_choice_in_use), or retired: a retired field leaves the forms and takes no new values; the values records hold stay readable. A field is never deleted.

Parameters

Request body

application/json (required): CustomFieldUpdate

Example request

curl -X PATCH "$ERP_URL/v1/custom-fields/7d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Sector"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "record": "company",
  "key": "string",
  "label": "string",
  "type": "choice",
  "choices": [
    "string"
  ],
  "position": 1,
  "retired": true
}

GET /v1/hubspot

Get HubSpot

Whether HubSpot can be connected here, whether HubSpot's consent page can be used, the permissions a private app needs, and each company connected: the account, the stage at which a contact becomes a lead, the default owner, how far HubSpot was read and the last error.

Example request

curl "$ERP_URL/v1/hubspot" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "available": true,
  "oauth": true,
  "client_id": "string",
  "scopes": [
    "string"
  ],
  "connections": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "entity": "string",
      "portal_id": 1,
      "account_url": "string",
      "method": "key",
      "stage": "lead",
      "owner": null,
      "status": "active",
      "read_to": "2026-09-21T09:30:00Z",
      "last_sync_at": "2026-09-21T09:30:00Z",
      "last_error": "string",
      "leads": 1,
      "linked_by": {},
      "linked_at": "2026-09-21T09:30:00Z"
    }
  ]
}

POST /v1/hubspot/authorize

Start connecting HubSpot on its consent page

HubSpot's consent page for the company: open url; HubSpot sends the browser back to redirect_uri with a code and a state for POST /v1/hubspot/connections/oauth, within 15 minutes. 409 when this system has no HubSpot app (connect with a private app instead).

Request body

application/json (required): HubSpotAuthorize

Example request

curl -X POST "$ERP_URL/v1/hubspot/authorize" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entity": "CH01",
  "stage": "marketingqualifiedlead"
}'

Responses

Example response (shape)

{
  "url": "string",
  "redirect_uri": "string"
}

POST /v1/hubspot/connections

Connect HubSpot with a private app

Connect a company with the access token of a private app in its own HubSpot. HubSpot is asked for the account (proving the token) and Stabiso's properties are added to its contacts. From then on its contacts at the hand-over stage come in as leads every 5 minutes (the first round reads the last 90 days), and each contact is sent what became of its lead. Connecting again replaces the token. 409 in a test copy or when the company is connected to another account; 422 when HubSpot refuses the token or a permission is missing.

Request body

application/json (required): HubSpotKeyInput

Example request

curl -X POST "$ERP_URL/v1/hubspot/connections" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "access_token": "pat-eu1-0b9c4d2e-7f1a-4c3b-9e8d-1a2b3c4d5e6f",
  "entity": "CH01",
  "stage": "marketingqualifiedlead"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entity": "string",
  "portal_id": 1,
  "account_url": "string",
  "method": "key",
  "stage": "lead",
  "owner": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "name": "string"
  },
  "status": "active",
  "read_to": "2026-09-21T09:30:00Z",
  "last_sync_at": "2026-09-21T09:30:00Z",
  "last_error": "string",
  "leads": 1,
  "linked_by": {},
  "linked_at": "2026-09-21T09:30:00Z"
}

POST /v1/hubspot/connections/oauth

Connect HubSpot with its consent page's answer

Finish connecting with the code and state HubSpot sent the browser back with (only for whoever started it). 422 when the state is not theirs or too old; 409 as above.

Request body

application/json (required): HubSpotOAuthInput

Example request

curl -X POST "$ERP_URL/v1/hubspot/connections/oauth" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "na1-6a2b-…",
  "state": "eyJvcmciOiI….Xq3v…"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entity": "string",
  "portal_id": 1,
  "account_url": "string",
  "method": "key",
  "stage": "lead",
  "owner": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "name": "string"
  },
  "status": "active",
  "read_to": "2026-09-21T09:30:00Z",
  "last_sync_at": "2026-09-21T09:30:00Z",
  "last_error": "string",
  "leads": 1,
  "linked_by": {},
  "linked_at": "2026-09-21T09:30:00Z"
}

PATCH /v1/hubspot/connections/{connection_id}

Change what HubSpot hands over

Change the hand-over stage or the default owner (from the next round on).

Parameters

Request body

application/json (required): HubSpotUpdate

Example request

curl -X PATCH "$ERP_URL/v1/hubspot/connections/7d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner_user_id": "",
  "stage": "lead"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entity": "string",
  "portal_id": 1,
  "account_url": "string",
  "method": "key",
  "stage": "lead",
  "owner": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "name": "string"
  },
  "status": "active",
  "read_to": "2026-09-21T09:30:00Z",
  "last_sync_at": "2026-09-21T09:30:00Z",
  "last_error": "string",
  "leads": 1,
  "linked_by": {},
  "linked_at": "2026-09-21T09:30:00Z"
}

DELETE /v1/hubspot/connections/{connection_id}

Disconnect HubSpot

Disconnect: nothing more is read or sent, and a consent's token is taken back at HubSpot (a private app's token is deleted in HubSpot). The leads stay, and so does which contact each came from, so connecting the same account again brings no contact in twice.

Parameters

Example request

curl -X DELETE "$ERP_URL/v1/hubspot/connections/7d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

POST /v1/hubspot/connections/{connection_id}/sync

Read HubSpot now

A round now (they run every 5 minutes): read the contacts that changed, make leads of the new ones and send each contact what became of its lead. 409 when HubSpot stopped accepting the connection (connect again) or in a test copy.

Parameters

Example request

curl -X POST "$ERP_URL/v1/hubspot/connections/7d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a/sync" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "read": 1,
  "new_leads": 1,
  "updated_leads": 1,
  "sent": 1,
  "connection": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entity": "string",
    "portal_id": 1,
    "account_url": "string",
    "method": "key",
    "stage": "lead",
    "owner": {
      "id": null,
      "email": null,
      "name": null
    },
    "status": "active",
    "read_to": "2026-09-21T09:30:00Z",
    "last_sync_at": "2026-09-21T09:30:00Z",
    "last_error": "string",
    "leads": 1,
    "linked_by": {},
    "linked_at": "2026-09-21T09:30:00Z"
  }
}

GET /v1/lead-forms

List website forms

The forms on the organization's websites that create leads, by name, with their public key, their own page and how many leads each created.

Parameters

Example request

curl "$ERP_URL/v1/lead-forms" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "active": true,
    "allowed_origins": [
      "https://www.example.ch"
    ],
    "created_at": "2026-10-20T08:00:00Z",
    "created_by": {
      "id": "user:alice",
      "name": "Alice",
      "type": "human"
    },
    "entity": "CH01",
    "id": "9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",
    "key": "lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a",
    "language": "de",
    "last_lead_at": "2026-10-23T09:12:00Z",
    "leads": 12,
    "name": "Contact us",
    "owner": {
      "email": "alice@example.com",
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Alice"
    },
    "page_path": "/forms/leads/lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a"
  }
]

POST /v1/lead-forms

Set up a website form

A form for a website: whoever fills it in becomes a lead of the company, owned by owner_user_id, with the source web_form. Link to or embed its own page (page_path), or send your website's own form to it (docs/erp/leads.md). A person's setting: 403 lead_form_agent for an agent. Needs an Idempotency-Key.

Request body

application/json (required): LeadFormInput

Example request

curl -X POST "$ERP_URL/v1/lead-forms" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "allowed_origins": [
    "https://www.example.ch"
  ],
  "entity": "CH01",
  "language": "de",
  "name": "Contact us",
  "owner_user_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "thank_you": "Danke! Wir melden uns innert eines Arbeitstages."
}'

Responses

Example response (shape)

{
  "active": true,
  "allowed_origins": [
    "https://www.example.ch"
  ],
  "created_at": "2026-10-20T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "entity": "CH01",
  "id": "9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",
  "key": "lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a",
  "language": "de",
  "last_lead_at": "2026-10-23T09:12:00Z",
  "leads": 12,
  "name": "Contact us",
  "owner": {
    "email": "alice@example.com",
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Alice"
  },
  "page_path": "/forms/leads/lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a"
}

PATCH /v1/lead-forms/{form_id}

Change or switch off a website form

Its name, owner, language, websites, thank-you text or page to go to; active: false switches it off (its key then answers 404). A form is never deleted: its leads name it.

Parameters

Request body

application/json (required): LeadFormUpdate

Example request

curl -X PATCH "$ERP_URL/v1/lead-forms/9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "allowed_origins": [
    "https://www.example.ch"
  ],
  "language": "fr"
}'

Responses

Example response (shape)

{
  "active": true,
  "allowed_origins": [
    "https://www.example.ch"
  ],
  "created_at": "2026-10-20T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "entity": "CH01",
  "id": "9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",
  "key": "lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a",
  "language": "de",
  "last_lead_at": "2026-10-23T09:12:00Z",
  "leads": 12,
  "name": "Contact us",
  "owner": {
    "email": "alice@example.com",
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Alice"
  },
  "page_path": "/forms/leads/lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a"
}

POST /v1/lead-forms/{form_id}/new-key

Give a website form a new key

A new public key, for a form whose key is abused: the old key stops working at once, so the website must get the new one.

Parameters

Example request

curl -X POST "$ERP_URL/v1/lead-forms/9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c/new-key" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "active": true,
  "allowed_origins": [
    "https://www.example.ch"
  ],
  "created_at": "2026-10-20T08:00:00Z",
  "created_by": {
    "id": "user:alice",
    "name": "Alice",
    "type": "human"
  },
  "entity": "CH01",
  "id": "9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",
  "key": "lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a",
  "language": "de",
  "last_lead_at": "2026-10-23T09:12:00Z",
  "leads": 12,
  "name": "Contact us",
  "owner": {
    "email": "alice@example.com",
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Alice"
  },
  "page_path": "/forms/leads/lf_0b9c4a2e7d1f4e3a9c5b6d7e8f9a0b1c_Qm3xV7pL2sK9tR4wY8zN1a"
}

GET /v1/leads

List leads

The people who may become customers, the newest first, with their status, source and owner. Read-only.

Parameters

Example request

curl "$ERP_URL/v1/leads" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "company": "Beispiel GmbH",
    "country": "DE",
    "created_at": "2026-10-23T09:12:00Z",
    "created_by": {
      "id": "system:web_form",
      "name": "Contact us",
      "type": "system"
    },
    "email": "eva@beispiel.example",
    "email_opt_out": false,
    "entity": "CH01",
    "erased": false,
    "first_name": "Eva",
    "form_id": "9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",
    "form_name": "Contact us",
    "id": "8e1f2a3b-4c5d-4e6f-9a7b-8c9d0e1f2a3b",
    "last_name": "Beispiel",
    "message": "Please send us a quote for 25 seats.",
    "name": "Eva Beispiel",
    "number": "LEAD-000042",
    "owner": {
      "email": "alice@example.com",
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Alice"
    },
    "role": "Head of Finance",
    "source": "web_form",
    "source_detail": "Contact us",
    "status": "new"
  }
]

POST /v1/leads

Add a lead

A person who may become a customer: name, company, e-mail, phone, where they came from (source) and who works on them (owner_user_id); it starts new. An agent may add one. Website forms add theirs themselves. Needs an Idempotency-Key.

Request body

application/json (required): LeadInput

Example request

curl -X POST "$ERP_URL/v1/leads" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Beispiel GmbH",
  "country": "DE",
  "email": "eva@beispiel.example",
  "entity": "CH01",
  "first_name": "Eva",
  "last_name": "Beispiel",
  "owner_user_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "phone": "+49 30 1234567",
  "role": "Head of Finance",
  "source": "event",
  "source_detail": "Swiss Finance Day 2026"
}'

Responses

Example response (shape)

{
  "company": "Beispiel GmbH",
  "country": "DE",
  "created_at": "2026-10-23T09:12:00Z",
  "created_by": {
    "id": "system:web_form",
    "name": "Contact us",
    "type": "system"
  },
  "email": "eva@beispiel.example",
  "email_opt_out": false,
  "entity": "CH01",
  "erased": false,
  "first_name": "Eva",
  "form_id": "9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",
  "form_name": "Contact us",
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-8c9d0e1f2a3b",
  "last_name": "Beispiel",
  "message": "Please send us a quote for 25 seats.",
  "name": "Eva Beispiel",
  "number": "LEAD-000042",
  "owner": {
    "email": "alice@example.com",
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Alice"
  },
  "role": "Head of Finance",
  "source": "web_form",
  "source_detail": "Contact us",
  "status": "new"
}

GET /v1/leads/summary

Count leads by status

How many leads the company has at each status, where the open ones came from, how many nobody owns, and how many were converted in the last 30 days.

Parameters

Example request

curl "$ERP_URL/v1/leads/summary?entity=CH01" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "by_status": {},
  "open_by_source": {},
  "unassigned": 1,
  "converted_last_30_days": 1
}

GET /v1/leads/{lead_id}

Get a lead

One lead; a converted one names its customer, contact and deal.

Parameters

Example request

curl "$ERP_URL/v1/leads/8e1f2a3b-4c5d-4e6f-9a7b-8c9d0e1f2a3b" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "company": "Beispiel GmbH",
  "country": "DE",
  "created_at": "2026-10-23T09:12:00Z",
  "created_by": {
    "id": "system:web_form",
    "name": "Contact us",
    "type": "system"
  },
  "email": "eva@beispiel.example",
  "email_opt_out": false,
  "entity": "CH01",
  "erased": false,
  "first_name": "Eva",
  "form_id": "9f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",
  "form_name": "Contact us",
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-8c9d0e1f2a3b",
  "last_name": "Beispiel",
  "message": "Please send us a quote for 25 seats.",
  "name": "Eva Beispiel",
  "number": "LEAD-000042",
  "owner": {
    "email": "alice@example.com",
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Alice"
  },
  "role": "Head of Finance",
  "source": "web_form",
  "source_detail": "Contact us",
  "status": "new"
}