Create a custom object

curl --request POST \
  --url https://{subdomain}.conveyour.com/api/custom/objects \
  --header 'Content-Type: application/json' \
  --header 'x-conveyour-token: <api-key>' \
  --data '
{
  "name": "vehicles",
  "label": "Vehicle",
  "label_plural": "Vehicles",
  "schema": {
    "make": {
      "title": "Make",
      "type": "Text"
    },
    "model": {
      "title": "Model",
      "type": "Text"
    },
    "year": {
      "title": "Year",
      "type": "Number"
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-conveyour-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'vehicles',
    label: 'Vehicle',
    label_plural: 'Vehicles',
    schema: {
      make: {title: 'Make', type: 'Text'},
      model: {title: 'Model', type: 'Text'},
      year: {title: 'Year', type: 'Number'}
    }
  })
};

fetch('https://{subdomain}.conveyour.com/api/custom/objects', 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: 'vehicles',
    label: 'Vehicle',
    label_plural: 'Vehicles',
    schema: {
      make: {title: 'Make', type: 'Text'},
      model: {title: 'Model', type: 'Text'},
      year: {title: 'Year', type: 'Number'}
    }
  })
};

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

import requests

url = "https://{subdomain}.conveyour.com/api/custom/objects"

payload = {
    "name": "vehicles",
    "label": "Vehicle",
    "label_plural": "Vehicles",
    "schema": {
        "make": {
            "title": "Make",
            "type": "Text"
        },
        "model": {
            "title": "Model",
            "type": "Text"
        },
        "year": {
            "title": "Year",
            "type": "Number"
        }
    }
}
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/custom/objects",
  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' => 'vehicles',
    'label' => 'Vehicle',
    'label_plural' => 'Vehicles',
    'schema' => [
        'make' => [
                'title' => 'Make',
                'type' => 'Text'
        ],
        'model' => [
                'title' => 'Model',
                'type' => 'Text'
        ],
        'year' => [
                'title' => 'Year',
                'type' => 'Number'
        ]
    ]
  ]),
  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": "Custom Object created",
  "data": {
    "id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "name": "vehicle",
    "label": "Vehicle",
    "label_plural": "Vehicles"
  }
}

{
  "status": "failed",
  "message": "Lacking necessary permission add_contacts",
  "data": {
    "permission": "add_contacts"
  }
}

{
  "status": "failed",
  "message": "<string>",
  "data": {}
}

Custom Objects

Create a custom object

Creates a new Custom Object definition.

Create a Custom Object definition

Permission: requires manage_custom_objects.

Field definitions go in schema, not fields. schema is an object keyed by field name, each value shaped {title, type, ...} — e.g. {"make": {"title": "Make", "type": "Text"}}. A fields key is not part of the model and is silently dropped, so a payload using it creates the record with no fields at all.

schema is not enforced. The model marks name, label and label_plural required but not schema, so an object can be created with no fields defined.

POST

api

custom

objects

Create a custom object

curl --request POST \
  --url https://{subdomain}.conveyour.com/api/custom/objects \
  --header 'Content-Type: application/json' \
  --header 'x-conveyour-token: <api-key>' \
  --data '
{
  "name": "vehicles",
  "label": "Vehicle",
  "label_plural": "Vehicles",
  "schema": {
    "make": {
      "title": "Make",
      "type": "Text"
    },
    "model": {
      "title": "Model",
      "type": "Text"
    },
    "year": {
      "title": "Year",
      "type": "Number"
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-conveyour-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'vehicles',
    label: 'Vehicle',
    label_plural: 'Vehicles',
    schema: {
      make: {title: 'Make', type: 'Text'},
      model: {title: 'Model', type: 'Text'},
      year: {title: 'Year', type: 'Number'}
    }
  })
};

fetch('https://{subdomain}.conveyour.com/api/custom/objects', 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: 'vehicles',
    label: 'Vehicle',
    label_plural: 'Vehicles',
    schema: {
      make: {title: 'Make', type: 'Text'},
      model: {title: 'Model', type: 'Text'},
      year: {title: 'Year', type: 'Number'}
    }
  })
};

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

import requests

url = "https://{subdomain}.conveyour.com/api/custom/objects"

payload = {
    "name": "vehicles",
    "label": "Vehicle",
    "label_plural": "Vehicles",
    "schema": {
        "make": {
            "title": "Make",
            "type": "Text"
        },
        "model": {
            "title": "Model",
            "type": "Text"
        },
        "year": {
            "title": "Year",
            "type": "Number"
        }
    }
}
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/custom/objects",
  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' => 'vehicles',
    'label' => 'Vehicle',
    'label_plural' => 'Vehicles',
    'schema' => [
        'make' => [
                'title' => 'Make',
                'type' => 'Text'
        ],
        'model' => [
                'title' => 'Model',
                'type' => 'Text'
        ],
        'year' => [
                'title' => 'Year',
                'type' => 'Number'
        ]
    ]
  ]),
  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": "Custom Object created",
  "data": {
    "id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "name": "vehicle",
    "label": "Vehicle",
    "label_plural": "Vehicles"
  }
}

{
  "status": "failed",
  "message": "Lacking necessary permission add_contacts",
  "data": {
    "permission": "add_contacts"
  }
}

{
  "status": "failed",
  "message": "<string>",
  "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

Short, singular identifier for this object type (e.g. "vehicle") — think of it like a tag. Must be unique within your org.

label

string

required

The singular human-readable label (e.g. "Vehicle"). Must be unique.

label_plural

string

required

The plural human-readable label (e.g. "Vehicles"). Must be unique.

schema

object

A map keyed by field name — each key is the field's identifier and each value is { "title": "...", "type": "..." }. title and type are required per field; type must be a StudlyCase value (see GET /api/custom/objects/schema). This is an object, not an array — passing an array creates fields named 0, 1, 2.

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 custom object definition. Reads the schema off the stored record, so the field set varies per organization.

Show child attributes

Get Started

Contacts

Messaging

Campaigns

Content

Custom Objects

Reporting

Administration

Create a custom object

Authorizations

Query Parameters

Body

Response