List Contacts

Retrieve your contacts with pagination and filtering. You can also fetch a single contact by ID.

List All Contacts

Retrieve a paginated list of contacts in your organization.

Endpoint

GET /contacts

Returns: 200 OK

Query Parameters

Parameter	Type	Default	Description
limit	number	20	Items per page (min: 1, max: 100)
after	string	—	Cursor — return items after this id (exclusive).
before	string	—	Cursor — return items before this id (exclusive).
email	string	—	Filter by email address. Exact match, case-insensitive.
phone_number	string	—	Filter by phone number. Exact match; separators and a bare country code (e.g. 966…) are normalized to E.164 first.
external_id	string	—	Filter by your own identifier. Exact match — how to check whether a person is already imported.
list_id	string	—	Filter by contact list ID
tag_id	string	—	Filter by tag ID
segment_id	string	—	Only the members of this segment, as of its last count (counted_at on the segment). Suppressed contacts are left out. Returns 409 segment_not_ready while the segment's status is processing, and 404 if the segment does not exist.

Results are returned newest first. See Pagination for cursor details.

Response

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
      "email": "john.doe@example.com",
      "phone_number": "+201234567890",
      "external_id": "user_10294",
      "first_name": "John",
      "last_name": "Doe",
      "source": "api",
      "properties": {
        "company": "Acme Inc"
      },
      "is_suppressed": false,
      "created_at": "2026-03-01T10:00:00.000Z",
      "updated_at": "2026-03-08T12:00:00.000Z"
    }
  ]
}

See Create Contact for the per-item field reference.

---

Examples

cURL

curl "https://api.arsel.sa/v1/contacts?limit=20" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/contacts?limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/contacts?limit=20",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/contacts?limit=20");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts?limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

For the next page, pass the id of the last item from the previous response as after:

cURL

curl "https://api.arsel.sa/v1/contacts?limit=20&after=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/contacts?limit=20&after=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a", {
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/contacts?limit=20&after=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/contacts?limit=20&after=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts?limit=20&after=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

Find a Contact by Email or Phone

email, phone_number and external_id are exact-match lookups. The response is still a list; it is empty when nothing matches.

cURL

curl "https://api.arsel.sa/v1/contacts?email=john.doe@example.com" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/contacts?email=john.doe@example.com", {
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/contacts?email=john.doe@example.com",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/contacts?email=john.doe@example.com");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts?email=john.doe@example.com");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

A phone number's + must be URL-encoded as %2B:

cURL

curl "https://api.arsel.sa/v1/contacts?phone_number=%2B201234567890" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/contacts?phone_number=%2B201234567890", {
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/contacts?phone_number=%2B201234567890",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/contacts?phone_number=%2B201234567890");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts?phone_number=%2B201234567890");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

Filter by List

cURL

curl "https://api.arsel.sa/v1/contacts?list_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a&limit=50" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/contacts?list_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a&limit=50", {
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/contacts?list_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a&limit=50",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/contacts?list_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a&limit=50");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts?list_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a&limit=50");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

Filter by Tag

cURL

curl "https://api.arsel.sa/v1/contacts?tag_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6b&limit=50" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/contacts?tag_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6b&limit=50", {
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/contacts?tag_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6b&limit=50",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/contacts?tag_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6b&limit=50");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts?tag_id=01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6b&limit=50");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

---

Get Contact Details

Retrieve a single contact by ID.

Endpoint

GET /contacts/:id

Returns: 200 OK

Path Parameters

Parameter	Type	Description
id	string	The contact ID

Response

Returns the same shape as Create Contact.

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "email": "john.doe@example.com",
  "phone_number": "+201234567890",
  "external_id": "user_10294",
  "first_name": "John",
  "last_name": "Doe",
  "source": "api",
  "properties": {
    "company": "Acme Inc",
    "job_title": "Software Engineer",
    "city": "Cairo"
  },
  "is_suppressed": false,
  "created_at": "2026-01-15T10:00:00.000Z",
  "updated_at": "2026-03-08T12:00:00.000Z"
}

Examples

cURL

curl "https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer $ARSEL_API_KEY"

JavaScript

const response = await fetch("https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a", {
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
  },
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.get(
    "https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var response = await client.GetAsync("https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

---

Error Responses

401 Unauthorized

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid API Key"
}