Create a folder

curl --request POST \
  --url https://{subdomain}.conveyour.com/api/bookmarks/folders \
  --header 'Content-Type: application/json' \
  --header 'x-conveyour-token: <api-key>' \
  --data '
{
  "name": "Recruiting"
}
'

const options = {
  method: 'POST',
  headers: {'x-conveyour-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Recruiting'})
};

fetch('https://{subdomain}.conveyour.com/api/bookmarks/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'x-conveyour-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Recruiting'})
};

fetch('https://{subdomain}.conveyour.com/api/bookmarks/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{subdomain}.conveyour.com/api/bookmarks/folders"

payload = { "name": "Recruiting" }
headers = {
    "x-conveyour-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{subdomain}.conveyour.com/api/bookmarks/folders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Recruiting'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-conveyour-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "ok",
  "message": "success",
  "data": {
    "id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "name": "Regional Groups"
  }
}

{
  "status": "failed",
  "message": "Token is either expired or does not have the correct permissions",
  "data": []
}

Groups (Bookmarks)

Create a folder

Creates a new bookmark folder.

Create a bookmark folder

Groups are called bookmarks in the API. The UI calls these Groups, but the model and every route use bookmarks. The name describes what the record actually is: a saved contact filter query — filters is a required field, and the saved query is what defines the segment, whether dynamic or static. “Bookmark” was the original word for saving that query; the UI later settled on “Group” for the same thing. Endpoint paths stay /api/bookmarks — only the naming in these docs follows the UI.

POST

/

api

/

bookmarks

/

folders

Create a folder

curl --request POST \
  --url https://{subdomain}.conveyour.com/api/bookmarks/folders \
  --header 'Content-Type: application/json' \
  --header 'x-conveyour-token: <api-key>' \
  --data '
{
  "name": "Recruiting"
}
'

const options = {
  method: 'POST',
  headers: {'x-conveyour-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Recruiting'})
};

fetch('https://{subdomain}.conveyour.com/api/bookmarks/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'x-conveyour-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Recruiting'})
};

fetch('https://{subdomain}.conveyour.com/api/bookmarks/folders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{subdomain}.conveyour.com/api/bookmarks/folders"

payload = { "name": "Recruiting" }
headers = {
    "x-conveyour-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{subdomain}.conveyour.com/api/bookmarks/folders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Recruiting'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-conveyour-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "ok",
  "message": "success",
  "data": {
    "id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "name": "Regional Groups"
  }
}

{
  "status": "failed",
  "message": "Token is either expired or does not have the correct permissions",
  "data": []
}

Authorizations

x-conveyour-token

string

header

required

Your API key token. Contacts endpoints require a Server-only — Full API key — see Authentication.

Query Parameters

teams[]

string[]

Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so teams=A&teams=B silently resolves to B alone. On requests with a JSON body you may send teams (no brackets) in the body instead.

Values that are not valid ObjectIds are silently ignored — a mistyped team ID behaves as if no team was sent. See the teams section of the API conventions guide.

Body

application/json

name

string

required

Display name for the folder.

Response

Success.

The common response envelope shared by all ConveYour endpoints.

status

enum<string>

ok on success, failed on error.

Available options:

ok,

failed

message

string

Human-readable description of the result.

data

object

A folder record. Create and update return this directly, so it carries NO child listings, no bookmarks_count / folders_count, and no editable / deletable flags — those are added only by the read endpoints.

Show child attributes