API v2

The next version of the Oblic API works with the objects you see in Oblic, journeys, segments and messages, for the workspace a person connects. It is authorized with OAuth 2.1 access tokens instead of API keys, and acts with that person's role. /external/v1 keeps working with your API keys.


Getting a token

API v2 never takes an API key: send one and the answer is 401 API_KEY_NOT_ACCEPTED. A person connects your application to one of their workspaces instead, and your application acts for them there.

This requires an Oblic deployment with its OAuth authorization server enabled, API v2 listed as an allowed resource, signing keys and the consent page configured, and your client registered. Contact Oblic support to confirm availability before integrating; the example URLs do not establish that a deployment is configured.

  1. Register your application. Contact Oblic support with your application's name, its redirect URIs and the scopes it needs, and you receive a client ID. Clients are public: there is no client secret, and every authorization uses PKCE. Only a server or a native app can use the API: no browser origin is allowed, at the token endpoint or the API.
  2. Send the person to sign in. Open the authorization endpoint with the resource that names API v2, and scope=read send if you send messages, or scope=read if you only read. The person signs in to Oblic, chooses the workspace and approves the scopes.
  3. Exchange the code at the token endpoint, with the same resource.
  4. Call the API with Authorization: Bearer <access token>.
Authorization serverhttps://api.oblic.app (its metadata is at /.well-known/oauth-authorization-server)
Authorization endpointhttps://api.oblic.app/oauth2/authorize
Token endpointhttps://api.oblic.app/oauth2/token
Resourcehttps://api.oblic.app/external/v2
PKCES256 only
Access tokenvalid for 1 hour by default
Refresh tokenreplaced at every use; by default it stops working after 30 days unused, and 90 days after the person connected

Exchange the code

curl -X POST https://api.oblic.app/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d code=THE_CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d resource=https://api.oblic.app/external/v2

A token issued for another resource, such as Oblic's MCP server, does not work here. A request without a usable token is answered 401 with a WWW-Authenticate header naming this resource's metadata, https://api.oblic.app/.well-known/oauth-protected-resource/external/v2.

Scopes and roles

  • Name
    read
    Type
    scope
    Description

    Ask for it always: a token without it is refused. Reads the workspace's journeys and segments, and the messages sent through the API.

  • Name
    send
    Type
    scope
    Description

    Allows email, SMS and WhatsApp sends to be queued as the organization; it does not mean the provider has delivered them. The person sees this scope on its own line before they allow it.

A scope never goes beyond the person's role, which Oblic checks on every request. Taking a role away, or removing the person from the organization, stops the token at once.

  • Journeys and segments are the workspace's that the person chose; any role there may read them.
  • Messages sent through the API belong to the organization's default workspace, as an API key's do. Sending needs the send scope and the Owner, Admin or Editor role in the default workspace; reading needs any role there.

A token is not held to your organization's IP allow-list for API keys: it is used from your application's own servers, and the person's role and the scopes they allowed are what bound it.


Endpoints

Every answer is {"status": "success", "data": …, "errors": null}, or "status": "error" with the errors.

MethodPathWhat it does
GET/external/v2/journeysThe workspace's campaigns, automations, WhatsApp bots and journeys built in Journeys itself, most recently changed first
GET/external/v2/journeys/{id}One journey
GET/external/v2/segmentsThe workspace's lists, then its dynamic segments
GET/external/v2/segments/{id}One segment
POST/external/v2/messages/emailSends an email from a verified sender
POST/external/v2/messages/smsSends an SMS that matches one of your DLT templates
POST/external/v2/messages/whatsappSends an approved WhatsApp template, or a reply within 24 hours
GET/external/v2/messagesThe messages sent through the API, newest first, with the parameters of v1's list
GET/external/v2/messages/{messageId}A message sent through the API, and what became of it

Listing journeys

  • Name
    offset
    Type
    integer
    Description

    Where the page starts; 0 by default.

  • Name
    limit
    Type
    integer
    Description

    How many journeys, from 1 to 100; 50 by default.

  • Name
    mode
    Type
    string
    Description

    campaign, automation, bot, or journey for one built in Journeys itself.

  • Name
    status
    Type
    string
    Description

    draft, scheduled, live, paused or done.

  • Name
    search
    Type
    string
    Description

    Part of a journey's name.

The page's nextOffset is where the next page starts, and is null on the last page.

List journeys

curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

{
  "status": "success",
  "data": {
    "journeys": [
      {
        "id": "CMP000R7ZM4Q2VXH00",
        "mode": "campaign",
        "name": "Weekly offer",
        "status": "live",
        "createdAt": "2026-10-01T09:30:00Z",
        "updatedAt": "2026-10-12T14:05:00Z"
      }
    ],
    "nextOffset": null
  },
  "errors": null
}

Sending a message

The bodies are those of /external/v1/messages. A send is queued and answered 202 with the message's id. Send the same Idempotency-Key header, of 1 to 255 characters, to retry safely, as v1's sends take it: the same send again returns the first message's id and sends nothing, and the same key with a different message is refused, 409 IDEMPOTENCY_CONFLICT. A key is your application's own, so another application, or an API key, that uses the same key sends its own message.

Send an email

curl -X POST https://api.oblic.app/external/v2/messages/email \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-4471-shipped' \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your order has shipped",
    "html": "<p>Your order 4471 is on its way.</p>"
  }'

Response

{
  "status": "success",
  "data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
  "errors": null
}

Read what became of it with GET /external/v2/messages/{messageId}.


Errors

StatusCodeMeaning
401MISSING_ACCESS_TOKENNo access token was sent
401INVALID_ACCESS_TOKENThe token has expired, was issued for another resource, lacks read, or its person has left the organization: refresh it, or connect again
401API_KEY_NOT_ACCEPTEDAn API key was sent: use it with /external/v1
403INSUFFICIENT_SCOPEThe token lacks the scope the route needs, named in the WWW-Authenticate header: connect again and allow it
403FORBIDDENThe person's role does not allow this
403EMAIL_SUSPENDEDThe account's email is suspended for its bounces or spam complaints, as on /external/v1
400BAD_REQUEST, INVALID_IDEMPOTENCY_KEYA parameter, header or body is missing or cannot be read
400the field's name, such as TOA field of the body is not valid
402INSUFFICIENT_BALANCEA marketing SMS or WhatsApp send needs funds in the paying wallet; sign-in codes, transactional messages and replies are not refused for an empty wallet
404JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUNDNot in the workspace, or not sent through the API
404NOT_FOUNDThere is no such route
405METHOD_NOT_ALLOWEDThe route does not take the request's method: the Allow header lists those it does
415UNSUPPORTED_MEDIA_TYPEThe body is not sent as application/json
422UNVERIFIED_SENDERThe email's sender is not a verified identity
429RATE_LIMITED, QUOTA_EXCEEDEDThe email is past the account's hourly limits or its monthly quota, as on /external/v1; Retry-After says when

An SMS or a WhatsApp message can also be refused with a code that says why, as on /external/v1: a template that is not approved, a number that opted out of marketing, a number that is not connected, or a limit reached, with a Retry-After header when trying again later helps.

Was this page helpful?