# ORQO API


- **Get started**
- [ORQO API](/docs): Manage contacts, send WhatsApp messages, run campaigns and read conversations from your own systems.
- [Quickstart](/docs/quickstart): Create an API token, add a contact and send your first WhatsApp message.
- [Authentication](/docs/authentication): Authenticate every request with an organization API token in the Authorization header.

- **Concepts**
- [Errors](/docs/errors): One error envelope for every failure, stable codes to branch on, and when it is safe to retry.
- [Pagination](/docs/pagination): Every list endpoint pages with a cursor. Pass meta.next_cursor back as ?cursor= until has_more is false.
- [Idempotency](/docs/idempotency): Send an Idempotency-Key with creating requests so that a retry never creates or sends twice.
- [Rate limits](/docs/rate-limits): 60 requests a minute per user. Read the X-RateLimit headers and back off on 429.
- [Versioning and changelog](/docs/versioning): How the v1 API changes, and what changed.

- **Guides**
- [Webhooks](/docs/webhooks): Start an ORQO automation from your own system with a signed HTTP request.

- **Reference**
- [API reference](/docs/api): Every endpoint of the ORQO REST API v1, generated from the OpenAPI spec.
- Account
  - [List notifications](/docs/api/account/list-notifications): The current user's in-app notifications, newest first.
  - [Mark a notification as read](/docs/api/account/mark-a-notification-as-read)
  - [Retrieve plan usage limits](/docs/api/account/retrieve-plan-usage-limits)
  - [Retrieve the current user](/docs/api/account/retrieve-the-current-user): The user the API token belongs to.
  - [Retrieve the organization](/docs/api/account/retrieve-the-organization): The organization the API token is bound to, with your role in it.
  - [Retrieve the subscription](/docs/api/account/retrieve-the-subscription): The organization's current plan, or `"data": null` when it has no
trial or subscription. Readable even without a subscription.
  - [Update the current user](/docs/api/account/update-the-current-user)
- Analytics
  - [Campaign funnel](/docs/api/analytics/campaign-funnel): Sent, delivered, read and failed counts of one campaign, delivery over
time and the most common failure reasons.
  - [Conversation activity](/docs/api/analytics/conversation-activity): Conversations resolved over time and the channel mix between `from`
and `to` (same range rules as message volume).
  - [Message volume](/docs/api/analytics/message-volume): Messages per channel between `from` and `to` (dates, `YYYY-MM-DD`;
default the last 30 days, at most 366 days).
- Campaigns
  - [Create a campaign](/docs/api/campaigns/create-a-campaign): Creates a draft. Launch it with `POST /campaigns/{id}/launch`. Send an
`Idempotency-Key` header to retry safely.
  - [Launch a campaign](/docs/api/campaigns/launch-a-campaign): Queues the campaign for sending (`202`), now or at `schedule_at`. A
campaign that cannot be launched is `422 launch_rejected`. Send an
`Idempotency-Key` header to retry safely.
  - [List campaign recipients](/docs/api/campaigns/list-campaign-recipients): Newest first, with each recipient's delivery status.
  - [List campaigns](/docs/api/campaigns/list-campaigns): Newest first. Filter by `channel` and `status`.
  - [Pause a campaign](/docs/api/campaigns/pause-a-campaign): Only queued or sending campaigns can be paused; any other status is
`409 invalid_state`.
  - [Retrieve a campaign](/docs/api/campaigns/retrieve-a-campaign): `stats` are recomputed from the recipients on every call.
  - [Update a campaign](/docs/api/campaigns/update-a-campaign): Only draft and paused campaigns can be edited; any other status is
`409 invalid_state`.
- Contacts
  - [Create or update a contact](/docs/api/contacts/create-or-update-a-contact): Contacts are matched like everywhere else in ORQO: by `phone_e164`, or
by `email` when no phone is given. A new contact is `201`; an existing
one (or a deleted one with that number, which is restored) is updated
and returned with `200`. `custom_fields` keys must be contact fields
defined in Settings. Send an `Idempotency-Key` header to retry safely.
  - [Delete a contact](/docs/api/contacts/delete-a-contact)
  - [List contacts](/docs/api/contacts/list-contacts): Newest first. Filter by `search` (name, email or phone), `segment_id`,
`tag` and `opt_in_whatsapp`.
  - [Retrieve a contact](/docs/api/contacts/retrieve-a-contact)
  - [Update a contact](/docs/api/contacts/update-a-contact): Only the fields you send change. A `phone_e164` another contact already
has is `422 validation_failed`.
- Conversations
  - [List conversation messages](/docs/api/conversations/list-conversation-messages): Oldest first.
  - [List conversations](/docs/api/conversations/list-conversations): Most recently active first. Filter by `channel`, `status` and
`assigned_to` (a user id).
  - [Retrieve a conversation](/docs/api/conversations/retrieve-a-conversation)
- Messages
  - [Send a message](/docs/api/messages/send-a-message): Send a WhatsApp text, approved template, interactive message, Flow, or
media message to a contact (`contact_id`) or directly to an E.164
number (`to`). Send an `Idempotency-Key` header (or `client_message_id`)
to retry safely: a retry returns the original message with
`Idempotent-Replayed: true`.
- Segments
  - [Create a segment](/docs/api/segments/create-a-segment): A dynamic segment is filled from its `rules` right away. Send an `Idempotency-Key` header to retry safely.
  - [List segment contacts](/docs/api/segments/list-segment-contacts): Newest first.
  - [List segments](/docs/api/segments/list-segments): Newest first.
  - [Retrieve a segment](/docs/api/segments/retrieve-a-segment)