Get Contacts

# Retrieve all contacts in your organization
curl -X GET "https://api.contactship.ai/v1/contacts" \
  -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 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()
    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)

[
  {
    "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"
  }
]

GET

contacts

# Retrieve all contacts in your organization
curl -X GET "https://api.contactship.ai/v1/contacts" \
  -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 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()
    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)

[
  {
    "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"
  }
]

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.

Response

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

Error Codes

400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing API key
500 Internal Server Error - Server-side error

Code Examples

# Retrieve all contacts in your organization
curl -X GET "https://api.contactship.ai/v1/contacts" \
  -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 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()
    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)

[
  {
    "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"
  }
]

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

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