Skip to main content
Use customer externalId values to connect your application’s records with Protodesk. Store the returned Protodesk IDs for subsequent requests.

​
Sync a customer

Use PUT /customers to upsert by externalId. This requires customers:write. See Upsert a customer for the complete schema.
This request writes to your workspace. Use a dedicated test workspace while developing.

​
Open a conversation

Use POST /conversations with the returned customerId. Include an externalId if your system already has a stable ticket or case identifier. The endpoint reference describes the subject, channel, routing, and other supported fields. Use an Idempotency-Key for creation requests you may need to retry. Read your workspace’s statuses and priorities rather than assuming every workspace uses the same values.

​
Associate a channel identity

A customer may have identities for different communication channels. Link a channel identity when your workflow needs a specific external address or channel identifier. Do not assume an email field alone establishes every channel connection.

​
Add messages and route work

Use the messages endpoint to add a message. Its public payload uses externalId, sender, body, channel, attachments, metadata, and internal where supported by the schema.
An outbound message can contact a real customer through a configured channel. Confirm the workspace, recipient, and channel before sending. A test-mode API key does not prevent delivery.
Assign conversations with the assignment endpoint, and resolve them with the resolution endpoint.

​
Keep your system current

Subscribe to webhooks for background updates, or use realtime events for a live server-side stream. Store event IDs so retries do not repeat your side effects.