Connect

Connect a social account or a site: send the user to the URL, Marsial brings them back to your redirectUrl.

Start connecting an account

GET/v1/connect/{platform}

Returns the URL to send the user to. When they finish, Marsial redirects to redirectUrl with connected=<platform>&accountId=…, with error=… if it failed, or with select=<sessionId> when the user must pick a page, organization, board, location or profile (Facebook, LinkedIn, Pinterest, Google Business, Snapchat) a channel (Slack) or a number (WhatsApp). In that case list the options and select one. Shopify needs shop (the store's myshopify.com domain). wordpress here connects WordPress.com sites; self-hosted sites use POST /connect/wordpress.

Parameters

platformstringrequired
profileIdstringrequired
The profile the account will belong to.
redirectUrlstring (uri)required
Where Marsial sends the user back when the connection finishes.
shopstring
Shopify only, required there: the store's myshopify.com domain (or its prefix).

Response 200

data

urlstring (uri)required
Send the user here to authorize the network.

curl "https://api.marsial.dev/v1/connect/instagram?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconnected" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/connect/instagram?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconnected', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/connect/instagram?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconnected",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Connect a self-hosted WordPress site

POST/v1/connect/wordpress

Self-hosted WordPress has no OAuth: create an Application Password in the WordPress profile of the user who will publish (Users → Profile → Application Passwords) and send it with that user's login. Marsial checks the site and the permissions before saving. The password is not stored by Marsial; revoke it in WordPress to cut access.

Body

profileIdstringrequired
The profile the site will belong to.
siteUrlstring (starts_with)required
The public root of the site, e.g. https://example.com.
usernamestringrequired
The WordPress login of the user who will publish.
max 200
applicationPasswordstringrequired
An Application Password created in that user's WordPress profile.
min 8max 200

Response 201

data

idstringrequired
profileIdstringrequired
platformstringrequired
usernamestring
displayNamestring
avatarUrlstring (uri)
statusstringrequired
Values: active · needs_reconnection · disconnected
connectedAtstring (date-time)required
updatedAtstring (date-time)required

curl -X POST "https://api.marsial.dev/v1/connect/wordpress" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prf_8f2k4d",
    "siteUrl": "https://blog.acme.com",
    "username": "editor",
    "applicationPassword": "abcd efgh ijkl mnop qrst uvwx"
  }'

const res = await fetch('https://api.marsial.dev/v1/connect/wordpress', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "profileId": "prf_8f2k4d",
    "siteUrl": "https://blog.acme.com",
    "username": "editor",
    "applicationPassword": "abcd efgh ijkl mnop qrst uvwx"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/connect/wordpress",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "profileId": "prf_8f2k4d",
        "siteUrl": "https://blog.acme.com",
        "username": "editor",
        "applicationPassword": "abcd efgh ijkl mnop qrst uvwx"
    },
)
data = res.json()["data"]

List what the user can pick

GET/v1/connect/sessions/{id}/options

The id is the select value Marsial added to your redirectUrl. Sessions expire after one hour.

Parameters

idstringrequired

Response 200

data

platformstringrequired
optionsobject[]required
options
- idstringrequired
- namestringrequired
- detailstring
- imageUrlstring (uri)

curl "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Pick an option and finish connecting

POST/v1/connect/sessions/{id}/select

Parameters

idstringrequired

Body

optionIdstringrequired
max 200

Response 201

data

idstringrequired
profileIdstringrequired
platformstringrequired
usernamestring
displayNamestring
avatarUrlstring (uri)
statusstringrequired
Values: active · needs_reconnection · disconnected
connectedAtstring (date-time)required
updatedAtstring (date-time)required

curl -X POST "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "optionId": "1042…"
  }'

const res = await fetch('https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "optionId": "1042…"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "optionId": "1042…"
    },
)
data = res.json()["data"]