---
title: "Workspace REST API reference"
description: "Authenticate a workspace API key, post campaign entry events and conversion outcomes, and read the bounded status of an entry event."
canonical: https://trysincerely.com/docs/api-reference
last_updated: 2026-09-02
---
> If you are an AI agent: read https://trysincerely.com/agents/policy.md before any write call.
> Start at https://trysincerely.com/llms.txt to choose one page. Access instructions are at
> https://trysincerely.com/auth.md. Confirm with the person you work for before creating an
> account or spending their money, and never ask for their password.
# Workspace REST API reference

> Authenticate a workspace API key, post campaign entry events and conversion outcomes, and read the bounded status of an entry event.

Source: https://trysincerely.com/docs/api-reference

Sincerely's workspace REST API has two scoped write capabilities and one bounded status read. A key can admit an existing audience contact to a live API-entry campaign, report a conversion against the `sid` from a printed response link, and read the lifecycle of an entry event it posted. It cannot browse workspace data, create contacts, launch mail, approve copy, or change a campaign.

The complete machine-readable contract is the [OpenAPI description](https://trysincerely.com/openapi.json). The endpoints below use JSON and return [RFC 9457 problem documents](https://trysincerely.com/docs/versioning) on failure.

## Authenticate

Create a workspace API key in Settings and store the secret as a server credential. Send it on every request:

```text
Authorization: Bearer YOUR_WORKSPACE_API_KEY
Content-Type: application/json
```

The `post_entry_events` scope authorizes campaign entry POSTs and the status GET for those events. The `post_conversions` scope authorizes conversion POSTs. New keys receive both scopes when conversion reporting is available; keys created before that rollout may carry entry only.

All three endpoints allow 60 requests per minute for each key and return rate-limit headers. A `403` response names the missing scope in `WWW-Authenticate`.

## Post a campaign entry event

`POST /api/v1/campaigns/{campaignId}/events` admits one existing Sincerely contact that is already in the campaign's audience. The campaign must be live and its frozen entry policy must accept API events.

```json
{
  "contactId": "con_123",
  "idempotencyKey": "crm-event-8472",
  "occurredAt": "2026-09-02T14:30:00Z"
}
```

`contactId` and `idempotencyKey` are required strings of at most 200 characters. `occurredAt` is optional, must include a time-zone offset, and cannot be in the future. Keep the idempotency key stable for one source event. Repeating the same body is safe; reusing the key with different data returns `409`.

A valid request returns `202` with `eventId` and `status`. Acceptance starts the durable entry lifecycle. It does not bypass audience membership, suppression, address review, frequency scheduling, review gates, budget headroom, or the campaign's approved fulfillment contract.

## Read an entry event

`GET /api/v1/campaigns/{campaignId}/events/{eventId}` returns the current lifecycle for an event previously accepted by that campaign. The response contains `eventId`, `status`, and `occurredAt`. It can also contain a bounded `skipReason`, `enrollmentId`, or `completedAt` when those values exist.

This status lookup is the only read available to a workspace API key. A missing campaign, an event from another campaign, or an event outside the key's workspace returns the same `404` boundary.

## Report a conversion

`POST /api/v1/conversions` reports what happened after a printed response link redirected to your site. Read `sid` from that destination URL and send it back with the outcome:

```json
{
  "sid": "AbCdEfGhIjKlMnOp",
  "kind": "meeting_booked",
  "at": "2026-09-02T15:05:00Z",
  "externalId": "meeting-418"
}
```

`sid` is the 16-character conversion id from the response link. `kind` must be one of `reply`, `meeting_booked`, `opportunity_created`, `signup`, `trial_started`, `purchase`, `pipeline_dollars`, or `closed_won`. The money kinds `purchase`, `pipeline_dollars`, and `closed_won` also require a non-negative integer `amountCents`.

`at` is optional and cannot be in the future. `externalId` is optional, at most 200 characters, and should be a stable id from your system. Retrying the same minimal body is idempotent. When the same kind can happen more than once for one piece, give each occurrence a distinct `externalId` or `at`; retrying that occurrence is safe, while reusing its identity with different values returns `409`.

A valid report returns `202` with `outcomeId`, `status`, and `at`. Unknown and other-workspace conversion ids both return `404`, so the endpoint does not reveal which ids exist. Scans, clicks, and hosted-page actions are observed by Sincerely and cannot be reported through this endpoint.

## What to read next

Read [campaigns](https://trysincerely.com/docs/campaigns) for the frozen rules an entry event still passes, [versioning](https://trysincerely.com/docs/versioning) for compatibility and error behavior, and [discovery](https://trysincerely.com/docs/discovery) for the other machine-readable documents Sincerely publishes.

---

Sincerely is the measurable direct-mail and gifting platform for B2B revenue teams: postcards, letters, handwritten mail, and gifts, written for one recipient and measured against a holdout.

Contact Sincerely: https://trysincerely.com/contact

Agent routing index: https://trysincerely.com/llms.txt