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.
The OpenAPI document for this version is external-v2.json, which the OpenAPI reference shows as version 2.
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.
- 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.
- Send the person to sign in. Open the authorization endpoint with the
resourcethat names API v2, andscope=read sendif you send messages, orscope=readif you only read. The person signs in to Oblic, chooses the workspace and approves the scopes. - Exchange the code at the token endpoint, with the same
resource. - Call the API with
Authorization: Bearer <access token>.
| Authorization server | https://api.oblic.app (its metadata is at /.well-known/oauth-authorization-server) |
| Authorization endpoint | https://api.oblic.app/oauth2/authorize |
| Token endpoint | https://api.oblic.app/oauth2/token |
| Resource | https://api.oblic.app/external/v2 |
| PKCE | S256 only |
| Access token | valid for 1 hour by default |
| Refresh token | replaced 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
sendscope 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.
| Method | Path | What it does |
|---|---|---|
GET | /external/v2/journeys | The 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/segments | The workspace's lists, then its dynamic segments |
GET | /external/v2/segments/{id} | One segment |
POST | /external/v2/messages/email | Sends an email from a verified sender |
POST | /external/v2/messages/sms | Sends an SMS that matches one of your DLT templates |
POST | /external/v2/messages/whatsapp | Sends an approved WhatsApp template, or a reply within 24 hours |
GET | /external/v2/messages | The 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;
0by default.
- Name
limit- Type
- integer
- Description
How many journeys, from 1 to 100;
50by default.
- Name
mode- Type
- string
- Description
campaign,automation,bot, orjourneyfor one built in Journeys itself.
- Name
status- Type
- string
- Description
draft,scheduled,live,pausedordone.
- 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
| Status | Code | Meaning |
|---|---|---|
| 401 | MISSING_ACCESS_TOKEN | No access token was sent |
| 401 | INVALID_ACCESS_TOKEN | The token has expired, was issued for another resource, lacks read, or its person has left the organization: refresh it, or connect again |
| 401 | API_KEY_NOT_ACCEPTED | An API key was sent: use it with /external/v1 |
| 403 | INSUFFICIENT_SCOPE | The token lacks the scope the route needs, named in the WWW-Authenticate header: connect again and allow it |
| 403 | FORBIDDEN | The person's role does not allow this |
| 403 | EMAIL_SUSPENDED | The account's email is suspended for its bounces or spam complaints, as on /external/v1 |
| 400 | BAD_REQUEST, INVALID_IDEMPOTENCY_KEY | A parameter, header or body is missing or cannot be read |
| 400 | the field's name, such as TO | A field of the body is not valid |
| 402 | INSUFFICIENT_BALANCE | A 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 |
| 404 | JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUND | Not in the workspace, or not sent through the API |
| 404 | NOT_FOUND | There is no such route |
| 405 | METHOD_NOT_ALLOWED | The route does not take the request's method: the Allow header lists those it does |
| 415 | UNSUPPORTED_MEDIA_TYPE | The body is not sent as application/json |
| 422 | UNVERIFIED_SENDER | The email's sender is not a verified identity |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | The 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.