IllyVoIPdevelopers

Contacts & Companies

List contacts

Returns contacts with status, company, sharing, and custom field data.

Try in API Playground ↗Sign in to prepare and run this request.
GET/api/v1/contacts

Before you start

Use filters and the documented pagination fields to limit the result set.

Result

Read contact IDs and external references for subsequent updates.

Charges and safe retries

Keep contact data private and follow the returned pagination rather than assuming one response contains every contact.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X GET "https://api.illyvoip.com/api/v1/contacts?q=alice&updated_since=2026-03-01+00%3A00%3A00&page=1&limit=50" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}"

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/contacts?q=alice&updated_since=2026-03-01+00%3A00%3A00&page=1&limit=50", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY
  }
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/contacts?q=alice&updated_since=2026-03-01+00%3A00%3A00&page=1&limit=50');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY')
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "GET",
    "https://api.illyvoip.com/api/v1/contacts?q=alice&updated_since=2026-03-01+00%3A00%3A00&page=1&limit=50",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"]
    },
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request parameters

Query parameters

qstringoptional

Name, email, or number search.

updated_sincestringoptional

Return contacts updated since this timestamp.

include_deletedbooleanoptional

Include soft-deleted contacts when true.

pageintegeroptional

Page number.

limitintegeroptional

Items per page.

default 100minimum 1maximum 500

Request behavior

Use q, page, and limit to build CRM selectors, outbound tools, or external sync jobs. id is always available; legacy contacts may return uuid: null until they are updated.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • contacts: Contacts available to this account and the requested filters.
  • pagination: Pagination state; follow the returned continuation values without constructing your own.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON
{
  "status": "success",
  "contacts": [
    {
      "id": 123,
      "uuid": "0c3a6f9e-3b2c-4c22-9c25-9b6f9c0b2a11",
      "firstname": "Alice",
      "lastname": "Example",
      "phone": "+15551230003",
      "email": "alice@example.test",
      "address": "Main Street 1",
      "zip": "10000",
      "country": "US",
      "call_status": "callback",
      "company": {
        "id": 88,
        "name": "Example Corp"
      },
      "shared_users": [
        {
          "id": 42,
          "name": "Alice Agent"
        }
      ],
      "custom_fields": [
        {
          "id": 5,
          "slug": "crm_id",
          "value": "C-1001"
        }
      ],
      "external": {
        "source": "crm",
        "id": "contact_123"
      },
      "created_at": "2026-03-01T09:00:00+00:00",
      "updated_at": "2026-03-31T09:15:00+00:00",
      "deleted_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 213,
    "total_pages": 5
  }
}
statusstringrequired
enum ["success"]
contactsarray<object>required
View nested fields

Array items

idintegerrequired
uuidstringrequired

Opaque contact UUID when assigned. Legacy contacts may return null; use the stable id selector.

nullable true
firstnamestringrequired
lastnamestringrequired
phonestringrequired
emailstringrequired
addressstringrequired
zipstringrequired
countrystringrequired
call_statusstringrequired
companyobjectrequired
View nested fields
idintegerrequired
namestringrequired

Additional properties: not allowed.

shared_usersarray<object>required
View nested fields

Array items

idintegerrequired
namestringrequired

Additional properties: not allowed.

custom_fieldsarray<object>required
View nested fields

Array items

idintegerrequired
slugstringrequired
valuestringrequired

Additional properties: not allowed.

externalobjectrequired
View nested fields
sourcestringrequired
idstringrequired

Additional properties: not allowed.

created_atstringrequired
updated_atstringrequired
deleted_atstringrequired
nullable true

Additional properties: not allowed.

paginationobjectrequired
View nested fields
pageintegerrequired
per_pageintegerrequired
totalintegerrequired
total_pagesintegerrequired

Additional properties: not allowed.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "contacts": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer"
          },
          "uuid": {
            "type": "string",
            "nullable": true,
            "description": "Opaque contact UUID when assigned. Legacy contacts may return null; use the stable id selector."
          },
          "firstname": {
            "type": "string"
          },
          "lastname": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "call_status": {
            "type": "string"
          },
          "company": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          },
          "shared_users": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            }
          },
          "custom_fields": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "integer"
                },
                "slug": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "slug",
                "value"
              ]
            }
          },
          "external": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "source": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            },
            "required": [
              "source",
              "id"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "deleted_at": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "uuid",
          "firstname",
          "lastname",
          "phone",
          "email",
          "address",
          "zip",
          "country",
          "call_status",
          "company",
          "shared_users",
          "custom_fields",
          "external",
          "created_at",
          "updated_at",
          "deleted_at"
        ]
      }
    },
    "pagination": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "page": {
          "type": "integer"
        },
        "per_page": {
          "type": "integer"
        },
        "total": {
          "type": "integer"
        },
        "total_pages": {
          "type": "integer"
        }
      },
      "required": [
        "page",
        "per_page",
        "total",
        "total_pages"
      ]
    }
  },
  "required": [
    "status",
    "contacts",
    "pagination"
  ]
}
400 The request failed validation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key or browser token is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 The account is not allowed to perform this operation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected service error occurred.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 The service is temporarily unavailable.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable

Try this operation in Sandbox · Environment setup and limitations

Create or update contactGet contact workspace metadataList companiesCreate or update companyArchive companyDelete contact

Search API operations, parameters, SDK and webhooks.