API reference for the DobroDesk Zapier integration

Base URL and access keys

The Zapier integration uses the production HTTPS API at https://dobrodesk.com/api/v1. Send an active DobroDesk Access key in the Authorization header on every request.

Create one key for Start automations and another for Add internal notes. The trigger key can read conversation metadata across the workspace, including IDs, Inbox, status, source channel and timestamps. It cannot read customer message text or attachments. An Inbox choice filters which events are delivered, but the trigger key can still read metadata across the workspace. The note key can add an internal note to a conversation in the workspace.

Purpose-scoped Zapier keys are the recommended self-service choice. The trigger key uses conversations:read and works on the documented trigger routes and the connection check. The note key uses conversations:write and works on the internal-note route and the connection check. Purpose-scoped keys are rejected from unrelated API endpoints with HTTP 403 and code api_token_purpose_forbidden. A generic active REST API key is also accepted on these Zapier routes under its normal scopes: the connection check needs no scope, read and subscription routes need conversations:read, and adding a note needs conversations:write. Generic keys keep their normal REST API access, so use the purpose-scoped keys for least privilege.

Treat an Access key like a password. Do not include it in a URL, browser code, a shared log or a Zapier webhook target URL.

Authorization: Bearer dd_live_<dedicated-access-key>

Check the connection

GET /zapier/connection checks that an active REST API key is valid and identifies its workspace and connection. It accepts generic API keys and either purpose-scoped Zapier key. No additional scope is required. A successful request returns HTTP 200.

The data object contains workspaceId, tokenId, scopes, workspaceName and connectionName. The endpoint does not return the Access key.

GET https://dobrodesk.com/api/v1/zapier/connection
Authorization: Bearer dd_live_<dedicated-access-key>

{
  "data": {
    "workspaceId": "<workspaceId>",
    "tokenId": "<tokenId>",
    "scopes": ["conversations:read"],
    "workspaceName": "<workspaceName>",
    "connectionName": "<connectionName>"
  }
}

Read Inbox choices and conversation samples

GET /zapier/inboxes?page=0&limit=100 returns a page of Inbox choices as data entries with id and name. page is an integer from 0 to 10,000 and defaults to 0. limit is an integer from 1 to 100 and defaults to 100.

GET /zapier/conversations?limit=3&inboxId=<inboxId> returns conversation metadata for Zapier's editor test step. inboxId is optional and, when provided, must be a non-empty string. limit is an integer from 1 to 100 and defaults to 10. Each result contains id, workspaceId, conversationId, status, sourceChannel and createdAt, with inboxId when present. id is the same conversation ID. No customer message text or attachments are returned.

Both routes require conversations:read. Use the purpose-scoped trigger key or an active generic REST API key with that scope. In the live trigger output, eventId identifies the event and occurredAt gives its event time. The conversation ID remains the stable identifier for the conversation.

GET /api/v1/zapier/inboxes?page=0&limit=100
GET /api/v1/zapier/conversations?limit=3&inboxId=<inboxId>

Create a New Conversation subscription

POST /zapier/subscriptions registers the Zapier REST Hook target and requires conversations:read. Use the purpose-scoped trigger key or an active generic REST API key with that scope. The JSON body requires targetUrl and can include inboxId as a string. Omitting inboxId subscribes to new conversations in every Inbox. A workspace can have up to 100 active webhook subscriptions across Zapier and other webhook integrations. A successful request returns HTTP 200 with the subscription ID in data.id.

DobroDesk accepts HTTPS targets only when the exact host is hooks.zapier.com. Do not include credentials, an explicit port or a URL fragment. Zapier supplies the path and query. The target URL is an opaque secret, so keep it private. An Inbox filter changes only which events are delivered. It does not restrict the trigger key's workspace-wide metadata access described above.

For each new conversation, DobroDesk sends a POST to the target URL with X-DobroDesk-Delivery, X-DobroDesk-Event: conversation.created and a JSON body containing deliveryId. The callback is not HMAC-signed. The Zapier trigger checks that the delivery ID in X-DobroDesk-Delivery matches deliveryId in the request body, then reads the canonical event from DobroDesk with its authenticated key.

POST /api/v1/zapier/subscriptions
Authorization: Bearer dd_live_<trigger-access-key>
Content-Type: application/json

{
  "targetUrl": "https://hooks.zapier.com/<Zapier-assigned-path>",
  "inboxId": "<inboxId>"
}

{
  "data": {
    "id": "<subscriptionId>"
  }
}

Read a delivered event and unsubscribe

GET /zapier/events/<deliveryId> requires conversations:read and the same key that created the subscription. It returns HTTP 200 with the canonical event only when the subscription is active. The response is an envelope with data.id, data.type, data.workspaceId, data.occurredAt and data.data. The type is conversation.created. Its nested data contains conversationId, optional inboxId, status, sourceChannel and createdAt.

The trigger exposes the event ID as eventId and the event time as occurredAt. It returns conversation metadata only. Customer message text and attachments are not part of this API response.

DELETE /zapier/subscriptions/<subscriptionId> requires conversations:read and the same key that created the subscription. It disables the subscription and returns HTTP 200 with data.id and data.disabled set to true. A missing, inactive or inaccessible subscription or event returns 404. Turn off the Zap before disconnecting its key so Zapier can unsubscribe cleanly.

GET /api/v1/zapier/events/<deliveryId>
Authorization: Bearer dd_live_<trigger-access-key>

DELETE /api/v1/zapier/subscriptions/<subscriptionId>
Authorization: Bearer dd_live_<trigger-access-key>

Add an internal note

POST /conversations/<conversationId>/notes requires conversations:write. Use the purpose-scoped note key or an active generic REST API key with that scope. Send a JSON body with bodyText. The text must contain 1 to 20,000 characters after trimming. After the note is stored, a successful request returns HTTP 200 with data.id and data.status set to saved. This action adds a note for teammates. It does not send a customer reply.

Send an Idempotency-Key with each write. In the Zapier action, map Source event or operation ID to a non-empty stable value of up to 1,024 characters. The connector hashes it with SHA-256 and sends a key beginning zapier-note- followed by 64 lowercase hexadecimal characters. A valid Idempotency-Key header value is 1 to 200 characters using only ASCII letters, digits and `.`, `_`, `:` or `-`. Keep the same Access key connection, Idempotency-Key, conversationId and note text when retrying. DobroDesk retains the result for 365 days, scoped to the workspace and Access key identity. Reusing a key with a different conversationId or note text returns HTTP 409 with code idempotency_conflict. If a retry returns idempotency_in_progress, wait briefly and replay with the same source ID, conversationId and note text. The connector does not promise an automatic retry.

POST /api/v1/conversations/<conversationId>/notes
Authorization: Bearer dd_live_<note-access-key>
Idempotency-Key: zapier-note-<sha256-of-source-reference>
Content-Type: application/json

{
  "bodyText": "Internal update from an approved automation."
}

{
  "data": {
    "id": "<noteId>",
    "status": "saved"
  }
}

Errors and rate limits

An absent, invalid, expired or revoked key returns HTTP 401. A purpose mismatch returns HTTP 403 with code api_token_purpose_forbidden. A missing scope returns HTTP 403 with code insufficient_scope and requiredScope.

Authorized API requests are limited to 300 per minute per key. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When the limit is exceeded, DobroDesk returns HTTP 429 with code rate_limit_exceeded and Retry-After. The limit is not an availability or delivery-time guarantee. A valid request may also return HTTP 5xx if the service is temporarily unavailable.

• GET /zapier/connection: zapier_connection_unavailable (503).
• GET /zapier/inboxes and GET /zapier/conversations: zapier_query_invalid (400).
• POST /zapier/subscriptions: zapier_subscription_invalid or zapier_target_url_invalid (400), inbox_not_found (404), zapier_subscription_conflict or zapier_subscription_limit_reached (409), and zapier_subscription_unavailable (503). A conflict means the target is already active with different settings. The subscription limit is 100 active webhook subscriptions per workspace.
• DELETE /zapier/subscriptions/<subscriptionId>: zapier_subscription_not_found (404).
• GET /zapier/events/<deliveryId>: zapier_event_not_found (404).
• POST /conversations/<conversationId>/notes: conversation_id_required (400), conversation_not_found (404), idempotency_key_required or internal_note_body_invalid (400), and idempotency_conflict or idempotency_in_progress (409). An idempotency_in_progress response means the same request is still being processed.

HTTP 403
data.code = api_token_purpose_forbidden

HTTP 429
data.code = rate_limit_exceeded