RESTJSONBearer auth

Yusr API reference

Use the tenant-scoped REST API to read conversations, send text replies, and manage contacts. Use outbound webhooks to receive product events in your own system.

Base URLhttps://yusr-ai.com/api/v1

Content typeapplication/json

No public DELETE endpoints are available. Archive or close conversations and update contacts instead.

Core concepts

Authentication

Every request requires a tenant-scoped API key in the Authorization header. Workspace owners generate the key from Team → API access. Yusr shows the full key once; keep it in a server-side secret store.

httpYusr API

Authorization: Bearer yusr_••••••••••••
Content-Type: application/json

Never expose an API key in browser code, mobile bundles, public repositories, or outbound webhook payloads. Rotating the key invalidates the previous value immediately.

Core concepts

Pagination

Collection endpoints use cursor pagination and return newest records first.

Parameter	Type	Required	Description
limit	integer	No	1–100 records. Uses the server default when omitted.
cursor	string	No	Opaque value from page.nextCursor.

jsonYusr API

{
  "data": [],
  "page": {
    "nextCursor": "eyJjcmVhdGVkQXQiOi..."
  }
}

Resources

Conversations

Read customer threads and send text replies through their connected provider.

List conversations

Returns conversations in the current workspace, newest first.

GET/conversations

Parameter	Type	Required	Description
limit	integer	No	Maximum records to return.
cursor	string	No	Cursor from the previous response.

bashYusr API

curl "https://yusr-ai.com/api/v1/conversations?limit=25" \
  -H "Authorization: Bearer $YUSR_API_KEY"

Response · 200 OK

jsonYusr API

{
  "data": [{
    "id": "conv_01J...",
    "platform": "whatsapp",
    "status": "open",
    "isAiBlocked": false,
    "unreadCount": 2,
    "lastMessageAt": "2026-07-31T18:42:10.000Z"
  }],
  "page": { "nextCursor": null }
}

List messages

Returns messages for one tenant-owned conversation.

GET/conversations/:id/messages

Response · 200 OK

jsonYusr API

{
  "data": [{
    "id": "msg_01J...",
    "conversationId": "conv_01J...",
    "senderType": "customer",
    "content": "Is this in stock?",
    "contentType": "text",
    "delivered": true,
    "read": true,
    "createdAt": "2026-07-31T18:42:10.000Z"
  }],
  "page": { "nextCursor": null }
}

Send a message

Sends a text reply through the conversation's connected channel.

POST/conversations/:id/messages

Parameter	Type	Required	Description
content	string	Yes	1–4,096 characters.

bashYusr API

curl -X POST "https://yusr-ai.com/api/v1/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $YUSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Your order is ready for pickup."}'

Response · 201 Created

jsonYusr API

{
  "data": {
    "id": "msg_01J...",
    "senderType": "agent",
    "content": "Your order is ready for pickup.",
    "contentType": "text"
  }
}

WhatsApp and Messenger reply-window rules still apply. A closed provider window returns 409 outside_window.

Resources

Contacts

Create and update CRM contacts and lead fields inside the current workspace.

List contacts

Returns contacts and leads, newest first.

GET/contacts

bashYusr API

curl "https://yusr-ai.com/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer $YUSR_API_KEY"

Create a contact

Creates a CRM contact. At least one of name, phone, or email is required.

POST/contacts

Parameter	Type	Required	Description
name	string	Conditional	Maximum 200 characters.
phone	string	Conditional	Maximum 50 characters.
email	string	Conditional	Valid email, maximum 200 characters.
stage	enum	No	new, contacted, qualified, negotiation, won, or lost.
lead_score	integer	No	0–100.
tags	string[]	No	Up to 20 tags; 50 characters each.

jsonYusr API

{
  "name": "Lina Haddad",
  "phone": "+97455501234",
  "email": "[email protected]",
  "stage": "qualified",
  "lead_score": 78,
  "tags": ["wholesale", "doha"]
}

Response · 201 Created

jsonYusr API

{
  "data": {
    "id": "contact_01J...",
    "name": "Lina Haddad",
    "stage": "qualified",
    "leadScore": 78,
    "isBlocked": false
  }
}

Update a contact

Updates one or more writable contact or lead fields.

PATCH/contacts/:id

bashYusr API

curl -X PATCH "https://yusr-ai.com/api/v1/contacts/$CONTACT_ID" \
  -H "Authorization: Bearer $YUSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage":"won","expected_value":12500}'

Changing a lead stage emits a lead.stage_changed event when outbound webhooks are enabled.

Events

Outbound webhooks

Configure HTTPS endpoints from Integrations. Each delivery contains an event envelope and an X-Yusr-Signature header calculated as HMAC-SHA256 over the raw request body.

message.receivedmessage.sentconversation.closedlead.createdlead.stage_changed

jsonYusr API

{
  "id": "evt_01J...",
  "event": "lead.stage_changed",
  "createdAt": "2026-07-31T18:45:00.000Z",
  "data": {
    "lead": { "id": "contact_01J...", "stage": "won" },
    "previousStage": "negotiation"
  }
}

Temporary failures retry after 1 minute, 5 minutes, and 30 minutes. Redirects, private-network destinations, and non-HTTPS URLs are rejected.

Reference

Errors

Errors use a stable machine-readable code in the response body.

jsonYusr API

{ "error": "invalid_request" }

StatusCodeMeaning

401unauthorizedThe bearer key is missing or invalid.

404not_foundThe resource does not exist in this workspace.

409outside_windowThe channel reply window is closed.

422invalid_requestParameters or JSON fields failed validation.

429rate_limitedThe workspace exceeded an API rate limit.

502send_failedThe connected provider rejected the outbound message.

503service_unavailableYusr could not complete the request.

Help

Get in touch

For integration questions, account help, or a custom deployment, contact the Yusr team.

General contact[email protected]Technical support[email protected]WhatsApp+90 554 144 90 99