Skip to main content

SemaswiftDocs

Auth API
Billing API
Voice API
Ticketing API
Engagements API
Uploads API
Automation API
Notifications API
Reports API
Surveys API
CRM API

Introduction
AddCollaborator grants a user collaborator access to this account via SpiceDB. Collaborators have the same read/write access as the owner but cannot delete the account or transfer ownership.
CreateAccount creates a new Account.
DeleteAccount soft-deletes an Account.
GetAccountDescendants returns a flat paginated list of all accounts below this one in the hierarchy, useful for rollup queries.
GetAccountHierarchy returns the full tree containing this account.
GetAccount retrieves a single Account by ID.
ListAccountContacts returns all contacts linked to this account via primary or secondary memberships, merged into a single list.
ListAccounts returns a paginated list of Accounts for the organisation.
ListCollaborators returns all users who have been granted collaborator access to this account.
MergeAccounts merges the source account into the target account.
RemoveCollaborator revokes a user's collaborator access to this account in SpiceDB.
SearchAccounts runs a full-text search across name, website, and phone.
SetOwner changes the account owner. Updates the SpiceDB owner relation, removing the previous owner's exclusive rights and granting them to the new owner.
UpdateAccount applies a partial update via an FieldMask.
GetActivity retrieves a single activity entry by its internal ID.
ListAccountActivities returns the activity timeline for a specific account, paginated and optionally filtered.
ListContactActivities returns the activity timeline for a specific contact, paginated and optionally filtered.
AddContactCollaborator grants a user collaborator access to this contact via SpiceDB.
AttachSecondaryAccount creates a secondary account membership for this contact. The contact can have many secondary memberships (e.g. board member at multiple companies).
ConvertLead transitions a contact from the lead stage to a later stage. Optionally creates a deal atomically via deal_params.
CreateContact creates a new contact.
DeleteContact soft-deletes a contact. Notes, activities, and memberships are retained as historical context.
DetachSecondaryAccount removes a secondary account membership.
GetContact retrieves a single contact by ID.
GetContactsByIDs batch-fetches contacts by ID list (up to 1000 per call).
ListContactAccounts returns the primary account and all secondary account memberships for a contact.
ListContactCollaborators returns all users with collaborator access to this contact.
ListContacts returns a paginated, filtered list of contacts.
MergeContacts merges the source contact into the target contact.
RemoveContactCollaborator revokes a user's collaborator access.
ReorderContactStages batch-updates the advisory sort_order of contact stages. Stages not in the list retain their current sort_order.
ResolveContactByChannel looks up (or creates) a contact by channel identifier (phone, email, or WhatsApp handle) within an organisation.
SearchContacts runs a full-text search across name, email, and phone.
SetContactOwner transfers ownership to a new user. Updates SpiceDB relations.
UpdateContact applies a FieldMask-driven partial update.
ArchiveCustomFieldDefinition sets `is_active = false` on a field.
CreateCustomFieldDefinition registers a new custom field for an object type.
GetCustomFieldDefinition retrieves a single definition by ID.
ListCustomFieldDefinitions returns all definitions for the organisation, optionally filtered by object type or section.
ReorderCustomFieldDefinitions batch-updates the section and position of multiple definitions in a single atomic operation.
UpdateCustomFieldDefinition modifies a field's mutable properties.
CreateDeal creates a new open deal.
CreateLineItem adds a line item to a deal and recomputes `Deal.value`.
DeleteDeal soft-deletes a deal and all its line items.
DeleteLineItem hard-deletes a line item and recomputes `Deal.value`.
GetDeal retrieves a single deal by ID.
ListDeals returns a paginated, filtered list of deals for the organisation.
ListLineItems returns all line items for a deal, ordered by `sort_order ASC`.
LostDeal marks a deal as lost. `close_reason` is required.
UpdateDeal applies a partial update to an open deal.
UpdateLineItem edits an existing line item and recomputes `Deal.value`.
WonDeal marks a deal as won. `close_reason` is required.
CreateDealStage creates a new pipeline stage for the organisation.
DeleteDealStage soft-deletes a pipeline stage.
GetDealStage retrieves a single pipeline stage by ID.
ListDealStages returns all active pipeline stages for the organisation, sorted by sort_order ASC. Soft-deleted stages are excluded.
ReorderDealStages atomically updates the sort_order of multiple stages.
UpdateDealStage modifies a stage's name, description, or probability.
CreateNote creates a new note on a contact or account.
DeleteNote soft-deletes a note. The note is excluded from future List and Get responses but the row is retained in the database.
GetNote retrieves a single note by ID.
ListNotes returns all active (non-deleted) notes for an object, paginated.
PinNote floats a note to the top of the object's note list.
UnpinNote returns a pinned note to its natural chronological position.
UpdateNote replaces the body of an existing note. Only the author or an admin can edit a note.
CancelTask marks a pending task as cancelled (terminal transition).
CompleteTask marks a pending task as completed (terminal transition).
CreateTask creates a new pending task.
DeleteTask soft-deletes a task. Can be called on any status.
GetTask retrieves a single task by ID.
ListTasks returns a paginated, filtered list of tasks for the organisation.
UpdateTask partially updates a pending task.
ArchiveFormDefinition transitions a form to `archived`. Submissions are rejected from this point forward; historical submissions remain queryable. Idempotent — archiving an already-archived form is a no-op.
CreateDraftFromPublished forks a published form into a new editable draft within the same name family, bumping `version` by one. Existing submissions against earlier versions are unaffected.
CreateFormDefinition creates a new form in `draft` status. The schema is validated for field key shape and uniqueness; submissions cannot be accepted until the form is published.
DeleteFormDefinition soft-deletes a draft or archived form. Forms with any submissions cannot be deleted — archive them instead (the docs and submissions remain queryable).
GetFormDefinition retrieves a single form by ID with its full schema and metadata, regardless of status.
ListFormDefinitions returns a paginated list of forms for the organisation. Ordered by name ASC, version DESC (so the latest version of each family appears first). Default page size is 50.
PublishFormDefinition flips a draft form to `published`, snapshots any custom-field picklist options into the schema, and starts accepting submissions. The form must have at least one non-section field.
UpdateFormDefinition patches a draft form's schema and description. Form `name` is immutable across versions and cannot be changed.
DeleteFormSubmission soft-deletes a submission. The row is retained for audit but excluded from List results and ignored by any downstream consumers (e.g. a pipeline run action that referenced this submission will no longer see it).
GetFormSubmission retrieves a single submission by ID, including the schema snapshot, values, and write-back outcome.
ListFormSubmissions returns a paginated list of submissions. Every filter is optional; combining them is an AND. Soft-deleted submissions are excluded. Ordered by submitted_at DESC.
SubmitForm validates the values against the form's published schema, persists an immutable submission row with the schema snapshot, and applies any configured write-back to contact / account custom fields in the same transaction.
ArchivePipelineDefinition transitions a pipeline to `archived`. New enrollments are rejected; in-flight runs continue to completion against their snapshot. Idempotent.
CreateDraftFromPublished forks a published pipeline into a new editable draft within the same name family, bumping `version` by one. In-flight runs against earlier versions are unaffected.
CreatePipelineDefinition creates a new pipeline in `draft` status. The schema is validated for stage/action key shape and uniqueness, graph reachability, and per-action-type config requirements.
DeletePipelineDefinition soft-deletes a draft or archived pipeline. Pipelines that have ever been enrolled cannot be deleted — archive them instead so the run history remains queryable.
GetPipelineDefinition retrieves a single pipeline by ID with its full schema and metadata, regardless of status.
ListPipelineDefinitions returns a paginated list of pipelines for the organisation. Ordered by name ASC, version DESC. Default page size is 50.
PublishPipelineDefinition flips a draft pipeline to `published` and starts accepting enrollments. Schema is re-validated against the full ruleset before the flip.
UpdatePipelineDefinition patches a draft pipeline's description, schema, and auto-enroll trigger. `name` and `subject_type` are immutable across versions.
CancelPipelineRun terminates a run permanently with a required reason. No further actions execute; pending action rows are marked `skipped`; the run transitions to `cancelled` and `cancel_reason` is recorded.
EnrollContact starts a new pipeline run with the given contact as the subject. The pipeline must be `published` with `subject_type = 'contact'`. The first stage's actions are materialised and the run enters `running` status.
EnrollDeal starts a new pipeline run with the given deal as the subject. The pipeline must be `published` with `subject_type = 'deal'`.
GetPipelineRun retrieves a single run by ID, including its current stage, status, accumulated variables, and lifecycle timestamps.
ListPipelineRunActions returns the per-action timeline for a single run, oldest-first. Each row represents one materialised action — form / checklist / create_deal / send_notification — with its status, completion metadata, and the JSON `result` snapshot used to feed downstream variable interpolation.
ListPipelineRuns returns a paginated list of runs. Every filter is optional; combining them is an AND. Ordered by started_at DESC.
PausePipelineRun freezes a running pipeline. `paused_at` is set; no new actions materialise. Completed actions can still record results, but stage transitions are deferred until ResumePipelineRun.
RestartPipelineRun rewinds the run to the given stage key, clearing every action that materialised at or after that stage along with the variables they produced. Actions are re-materialised and the run resumes from `from_stage_key`. Restartable from any status; terminal runs become `running` again.
ResumePipelineRun lifts the pause and continues from the current stage, re-evaluating branches against the current variables bag.

PinNote floats a note to the top of the object's note list.

PinNote floats a note to the top of the object's note list.

POST /api/v1/crm/notes/:id:pin

Errors:

NOT_FOUND: note does not exist.

Request

Responses

200
default

A successful response.

An unexpected error response.

ListNotes returns all active (non-deleted) notes for an object, paginated.

UnpinNote returns a pinned note to its natural chronological position.

Documentation

Getting Started
Authentication
API Reference

API Services

Auth API
Billing API
Voice API
Ticketing API
Reports API
Notifications API
Surveys API
CRM API

More

Changelog
GitHub
Support

Copyright © 2026 Semaswift. All rights reserved.