> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Contacts

> Retrieve all contacts from the organization with filtering options

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

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication. You can find this in your dashboard under API settings.
</ParamField>

## Query Parameters

<ParamField query="full_name" type="string">
  Filter contacts by full name (partial match). For example, using "John" will return all contacts with "John" in their name.
</ParamField>

<ParamField query="email" type="string">
  Filter contacts by email address (partial match). For example, using "gmail" will return all contacts with Gmail addresses.
</ParamField>

<ParamField query="phone_number" type="string">
  Filter contacts by phone number (partial match). For example, using "+1212" will return contacts with phone numbers starting with +1212.
</ParamField>

## Response

<ResponseField name="status code" type="number">
  200 on success
</ResponseField>

<ResponseField name="data" type="array">
  Array of contact objects

  <Expandable title="Contact object">
    <ResponseField name="id" type="string">
      The unique identifier of the contact (UUID format)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The timestamp when the contact was created (ISO 8601 format)
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number of the contact in international format (e.g., +12124567890)
    </ResponseField>

    <ResponseField name="full_name" type="string">
      The full name of the contact
    </ResponseField>

    <ResponseField name="country" type="string">
      The country of the contact
    </ResponseField>

    <ResponseField name="email" type="string">
      The email of the contact
    </ResponseField>

    <ResponseField name="description" type="string">
      Description or notes about the contact
    </ResponseField>

    <ResponseField name="additional_data" type="array">
      Additional data associated with the contact, each as a key-value pair with a type
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      The ID of the organization the contact belongs to
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Codes

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

## Code Examples

<RequestExample>
  ```bash cURL Example (All Contacts) theme={null}
  # Retrieve all contacts in your organization
  curl -X GET "https://api.contactship.ai/v1/contacts" \
    -H "x-api-key: your-api-key"
  ```

  ```bash cURL Example (Filtered by name) theme={null}
  # 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"
  ```

  ```bash cURL Example (Multiple filters) theme={null}
  # 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"
  ```

  ```javascript JavaScript Example theme={null}
  // 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();
  ```

  ```python Python Example theme={null}
  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)
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  [
    {
      "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"
    }
  ]
  ```
</ResponseExample>

## 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