Get Contacts

# Retrieve the first page of contacts (1000 per page)
curl -X GET "https://api.contactship.ai/v1/contacts?limit=1000&offset=0" \
  -H "x-api-key: your-api-key"

# Search for contacts with "Juan" in their name
curl -X GET "https://api.contactship.ai/v1/contacts?full_name=Juan" \
  -H "x-api-key: your-api-key"

# Search for contacts with both name and phone number criteria
curl -X GET "https://api.contactship.ai/v1/contacts?full_name=Juan&phone_number=%2B1212" \
  -H "x-api-key: your-api-key"

// Using Fetch API to get all contacts
const fetchContacts = async () => {
  try {
    const response = await fetch('https://api.contactship.ai/v1/contacts', {
      method: 'GET',
      headers: {
        'x-api-key': 'your-api-key'
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const { data: contacts } = await response.json();
    console.log('Contacts retrieved:', contacts);
    return contacts;
  } catch (error) {
    console.error('Error fetching contacts:', error);
  }
};

// Call the function
fetchContacts();

import requests

# Replace with your actual API key
api_key = "your-api-key"

# Base URL for the API
base_url = "https://api.contactship.ai"

# Headers
headers = {
    "x-api-key": api_key
}

# Optional: Add query parameters for filtering
params = {
    "full_name": "Juan",  # Optional: Filter by name
    # "email": "example.com",  # Optional: Filter by email domain
    # "phone_number": "+1212"  # Optional: Filter by phone number
}

# Make the GET request
response = requests.get(f"{base_url}/v1/contacts", headers=headers, params=params)

# Check if the request was successful
if response.status_code == 200:
    contacts = response.json()["data"]
    print(f"Found {len(contacts)} contacts")
    for contact in contacts:
        print(f"Name: {contact['full_name']}, Phone: {contact['phone_number']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

{
  "statusCode": 200,
  "data": [
    {
      "id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
      "created_at": "2023-01-01T12:00:00Z",
      "phone_number": "+12124567890",
      "full_name": "Juan Pérez",
      "country": "México",
      "email": "juan@ejemplo.com",
      "description": "Lead from LinkedIn campaign",
      "additional_data": [
        {
          "type": "location",
          "field": "dirección",
          "value": "Av. Insurgentes 123"
        },
        {
          "type": "text",
          "field": "notas",
          "value": "Cliente potencial para servicio premium"
        }
      ],
      "organization_id": "org123456"
    },
    {
      "id": "d5e6f7g8-h9i0-j1k2-l3m4-n5o6p7q8r9s0",
      "created_at": "2023-01-05T09:30:00Z",
      "phone_number": "+12125678901",
      "full_name": "Juan Martínez",
      "country": "Colombia",
      "email": "juan.martinez@ejemplo.com",
      "description": "Cliente potencial",
      "additional_data": [],
      "organization_id": "org123456"
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 2,
    "total_pages": 1
  }
}

GET

contacts

# Retrieve the first page of contacts (1000 per page)
curl -X GET "https://api.contactship.ai/v1/contacts?limit=1000&offset=0" \
  -H "x-api-key: your-api-key"

# Search for contacts with "Juan" in their name
curl -X GET "https://api.contactship.ai/v1/contacts?full_name=Juan" \
  -H "x-api-key: your-api-key"

# Search for contacts with both name and phone number criteria
curl -X GET "https://api.contactship.ai/v1/contacts?full_name=Juan&phone_number=%2B1212" \
  -H "x-api-key: your-api-key"

// Using Fetch API to get all contacts
const fetchContacts = async () => {
  try {
    const response = await fetch('https://api.contactship.ai/v1/contacts', {
      method: 'GET',
      headers: {
        'x-api-key': 'your-api-key'
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const { data: contacts } = await response.json();
    console.log('Contacts retrieved:', contacts);
    return contacts;
  } catch (error) {
    console.error('Error fetching contacts:', error);
  }
};

// Call the function
fetchContacts();

import requests

# Replace with your actual API key
api_key = "your-api-key"

# Base URL for the API
base_url = "https://api.contactship.ai"

# Headers
headers = {
    "x-api-key": api_key
}

# Optional: Add query parameters for filtering
params = {
    "full_name": "Juan",  # Optional: Filter by name
    # "email": "example.com",  # Optional: Filter by email domain
    # "phone_number": "+1212"  # Optional: Filter by phone number
}

# Make the GET request
response = requests.get(f"{base_url}/v1/contacts", headers=headers, params=params)

# Check if the request was successful
if response.status_code == 200:
    contacts = response.json()["data"]
    print(f"Found {len(contacts)} contacts")
    for contact in contacts:
        print(f"Name: {contact['full_name']}, Phone: {contact['phone_number']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

{
  "statusCode": 200,
  "data": [
    {
      "id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
      "created_at": "2023-01-01T12:00:00Z",
      "phone_number": "+12124567890",
      "full_name": "Juan Pérez",
      "country": "México",
      "email": "juan@ejemplo.com",
      "description": "Lead from LinkedIn campaign",
      "additional_data": [
        {
          "type": "location",
          "field": "dirección",
          "value": "Av. Insurgentes 123"
        },
        {
          "type": "text",
          "field": "notas",
          "value": "Cliente potencial para servicio premium"
        }
      ],
      "organization_id": "org123456"
    },
    {
      "id": "d5e6f7g8-h9i0-j1k2-l3m4-n5o6p7q8r9s0",
      "created_at": "2023-01-05T09:30:00Z",
      "phone_number": "+12125678901",
      "full_name": "Juan Martínez",
      "country": "Colombia",
      "email": "juan.martinez@ejemplo.com",
      "description": "Cliente potencial",
      "additional_data": [],
      "organization_id": "org123456"
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 2,
    "total_pages": 1
  }
}

This endpoint allows you to retrieve all contacts from your organization’s database. You can use various filtering options to narrow down the results based on specific criteria like name, email, or phone number.

Use Cases

Retrieve a list of all contacts in your organization
Search for contacts by name, email, or phone number
Populate contact lists in your application
Export contact data for analysis or reporting

Headers

string

requerido

Your API key for authentication. You can find this in your dashboard under API settings.

Query Parameters

string

Filter contacts by full name (partial match). For example, using “John” will return all contacts with “John” in their name.

string

Filter contacts by email address (partial match). For example, using “gmail” will return all contacts with Gmail addresses.

string

Filter contacts by phone number (partial match). For example, using “+1212” will return contacts with phone numbers starting with +1212.

number

Maximum number of contacts to return per page, up to 1000. Must be sent together with offset.

number

Number of contacts to skip. Must be sent together with limit: sending one without the other returns 400. If both are omitted, the API returns up to 10,000 contacts and pagination.page / pagination.total_pages are null.

string

Sort direction by creation date. Possible values: asc, desc.

To export your whole contact base, iterate with limit=1000 and increase offset until you have fetched pagination.total_rows contacts. For request throttling, see Rate Limits.

Response

The response contains statusCode, a data array, and pagination with page, total_rows, and total_pages.

number

200 on success

array

Array of contact objects

Mostrar Contact object

string

The unique identifier of the contact (UUID format)

string

The timestamp when the contact was created (ISO 8601 format)

string

The phone number of the contact in international format (e.g., +12124567890)

string

The full name of the contact

string

The country of the contact

string

The email of the contact

string

Description or notes about the contact

array

Additional data associated with the contact, each as a key-value pair with a type

string

The ID of the organization the contact belongs to

object

Pagination metadata for the request

Mostrar Pagination object

number

Current page, derived from offset and limit (null when the request was not paginated)

number

Total number of contacts matching the filters, across all pages

number

Total number of pages for the requested limit (null when the request was not paginated)

Error Codes

400 Bad Request - Invalid request parameters (for example limit above 1000, or limit without offset)
401 Unauthorized - Invalid or missing API key
429 Too Many Requests - Rate limit exceeded; honor Retry-After when present and use bounded backoff. See Rate Limits
500 Internal Server Error - Server-side error

Code Examples

# Retrieve the first page of contacts (1000 per page)
curl -X GET "https://api.contactship.ai/v1/contacts?limit=1000&offset=0" \
  -H "x-api-key: your-api-key"

# Search for contacts with "Juan" in their name
curl -X GET "https://api.contactship.ai/v1/contacts?full_name=Juan" \
  -H "x-api-key: your-api-key"

# Search for contacts with both name and phone number criteria
curl -X GET "https://api.contactship.ai/v1/contacts?full_name=Juan&phone_number=%2B1212" \
  -H "x-api-key: your-api-key"

// Using Fetch API to get all contacts
const fetchContacts = async () => {
  try {
    const response = await fetch('https://api.contactship.ai/v1/contacts', {
      method: 'GET',
      headers: {
        'x-api-key': 'your-api-key'
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const { data: contacts } = await response.json();
    console.log('Contacts retrieved:', contacts);
    return contacts;
  } catch (error) {
    console.error('Error fetching contacts:', error);
  }
};

// Call the function
fetchContacts();

import requests

# Replace with your actual API key
api_key = "your-api-key"

# Base URL for the API
base_url = "https://api.contactship.ai"

# Headers
headers = {
    "x-api-key": api_key
}

# Optional: Add query parameters for filtering
params = {
    "full_name": "Juan",  # Optional: Filter by name
    # "email": "example.com",  # Optional: Filter by email domain
    # "phone_number": "+1212"  # Optional: Filter by phone number
}

# Make the GET request
response = requests.get(f"{base_url}/v1/contacts", headers=headers, params=params)

# Check if the request was successful
if response.status_code == 200:
    contacts = response.json()["data"]
    print(f"Found {len(contacts)} contacts")
    for contact in contacts:
        print(f"Name: {contact['full_name']}, Phone: {contact['phone_number']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

{
  "statusCode": 200,
  "data": [
    {
      "id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
      "created_at": "2023-01-01T12:00:00Z",
      "phone_number": "+12124567890",
      "full_name": "Juan Pérez",
      "country": "México",
      "email": "juan@ejemplo.com",
      "description": "Lead from LinkedIn campaign",
      "additional_data": [
        {
          "type": "location",
          "field": "dirección",
          "value": "Av. Insurgentes 123"
        },
        {
          "type": "text",
          "field": "notas",
          "value": "Cliente potencial para servicio premium"
        }
      ],
      "organization_id": "org123456"
    },
    {
      "id": "d5e6f7g8-h9i0-j1k2-l3m4-n5o6p7q8r9s0",
      "created_at": "2023-01-05T09:30:00Z",
      "phone_number": "+12125678901",
      "full_name": "Juan Martínez",
      "country": "Colombia",
      "email": "juan.martinez@ejemplo.com",
      "description": "Cliente potencial",
      "additional_data": [],
      "organization_id": "org123456"
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 2,
    "total_pages": 1
  }
}

Notes and Best Practices

Use filtering parameters to reduce the amount of data transferred and improve performance
Implement pagination in your application if you expect a large number of contacts
Consider caching the results if you make frequent requests for the same data
The API returns a maximum of 100 contacts per request by default

Documentación API

Voz

WhatsApp (WABA)

Canales y conversaciones

Organización

Agentes

Contactos

Etiquetas

Llamadas

Tareas

Números de teléfono

Use Cases

Headers

Query Parameters

Response

Error Codes

Code Examples

Notes and Best Practices

​Use Cases

​Headers

​Query Parameters

​Response

​Error Codes

​Code Examples

​Notes and Best Practices

Use Cases

Headers

Query Parameters

Response

Error Codes

Code Examples

Notes and Best Practices