List contacts

curl --request GET \
  --url https://{subdomain}.conveyour.com/api/contacts \
  --header 'x-conveyour-token: <api-key>'

const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};

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

const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{subdomain}.conveyour.com/api/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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": "38 contacts found",
  "data": {
    "page": 1,
    "pages": 1,
    "count": 38,
    "results": [
      {
        "id": "6a1445f03af9bb089d10e1ad",
        "con_id": "6a1445f03af9bb089d10e1ad",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "mobile": "+15555550100",
        "tags": [
          "onboarding",
          "southwest"
        ],
        "shirt_size": "L",
        "crew_role": "Installer",
        "hire_date": 1718438400,
        "certification_expires": "2027-03-14T00:00:00+00:00",
        "supervisor_child_cnt": 3
      }
    ]
  }
}

Contacts

List contacts

Returns a list of contacts in your org.

Pagination is driven by limit, not page. The maximum page size is 50:

limit omitted, or limit ≥ 50 → paginated. data contains page, pages, count and results, and message is "N contacts found".
limit below 50 → not paginated. data contains only results, and message is "success".

Contacts are always in data.results — never a flat array. Each result carries both id and con_id (the same value) alongside the contact’s field keys.

Requires the contacts permission on the service account that owns your API key. A key whose service account lacks it fails with "Lacking necessary permission contacts".

Permission: requires contacts.

Custom fields appear flat, keyed by machine name. In the example below shirt_size, crew_role, hire_date, certification_expires and tags are all org-defined — your org will have a different set. Two things to note about their values: date fields whose suffix is First or Last (and any relative-time field) come back as a Unix timestamp like hire_date, while other date fields are ISO-formatted like certification_expires; and every related-contact field also yields a <field>_child_cnt integer, such as supervisor_child_cnt. Use the fields parameter to project just the ones you need.

GET

api

contacts

List contacts

curl --request GET \
  --url https://{subdomain}.conveyour.com/api/contacts \
  --header 'x-conveyour-token: <api-key>'

const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};

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

const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{subdomain}.conveyour.com/api/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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": "38 contacts found",
  "data": {
    "page": 1,
    "pages": 1,
    "count": 38,
    "results": [
      {
        "id": "6a1445f03af9bb089d10e1ad",
        "con_id": "6a1445f03af9bb089d10e1ad",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "mobile": "+15555550100",
        "tags": [
          "onboarding",
          "southwest"
        ],
        "shirt_size": "L",
        "crew_role": "Installer",
        "hire_date": 1718438400,
        "certification_expires": "2027-03-14T00:00:00+00:00",
        "supervisor_child_cnt": 3
      }
    ]
  }
}

Authorizations

x-conveyour-token

string

header

required

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

Query Parameters

format

enum<string>

Use v2 for the current response shape. Recommended for all new integrations.

Available options:

v2

archived

enum<string>

Filter by archive state. Omit for active only (default), just for archived only, with for all.

Available options:

just,

with

string

Search contacts by name, email, or phone number.

filters

object

Filter contacts by field value. Use Add property: the property name is the contact field key, the value is what to match. Serialized as filters[field_name]=value — e.g. filters[email]=jane@example.com. Any contact field key works, including org-defined custom fields.

Show child attributes

sort

object

Sort by field. Use Add property: the property name is the field key, the value is 1 (ascending) or -1 (descending). Serialized as sort[field_name]=1 — e.g. sort[created_at]=-1.

Show child attributes

count

enum<integer>

Pass count=1 to return only a contact count instead of records. Response: { "message": "contacts count", "data": { "count": 142 } }.

Available options:

1

page

integer

Page number (1-based). Only has an effect when the response is paginated — i.e. when limit is omitted or is 50.

Required range: x >= 1

limit

integer

default:50

Maximum contacts per page. Capped at 50, which is also the default. Passing a value below 50 turns pagination off — data then contains only results.

Required range: x <= 50

fields

string

Comma-separated list of field keys to include in each contact (projection). Omit for all fields. id, con_id and photo are always returned.

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.

expected_value

string

CSV export only. What the encrypted column should contain. Defaults to encrypted.

public_key

string

CSV export only. RSA public key used to encrypt sensitive columns. Required when the org enables require_public_encryption_key.

Response

A list of contacts. Shape depends on limit — see the description.

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

Contacts plus pagination. page, pages and count are present ONLY when the request paginates — getPaginated() disables pagination whenever limit is below limits.contacts, and then returns results alone. Passing count=true instead returns just {count}.

Show child attributes

Get Started

Contacts

Messaging

Campaigns

Content

Custom Objects

Reporting

Administration

List contacts

Authorizations

Query Parameters

Response