Saltar al contenido principal
GET
/
v1
/
contacts
# Retrieve all contacts in your organization
curl -X GET "https://api.contactship.ai/v1/contacts" \
  -H "x-api-key: your-api-key"

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

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.

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

​
x-api-key
string
requerido
Your API key for authentication. You can find this in your dashboard under API settings.

​
Query Parameters

​
full_name
string
Filter contacts by full name (partial match). For example, using “John” will return all contacts with “John” in their name.
​
email
string
Filter contacts by email address (partial match). For example, using “gmail” will return all contacts with Gmail addresses.
​
phone_number
string
Filter contacts by phone number (partial match). For example, using “+1212” will return contacts with phone numbers starting with +1212.

​
Response

​
status code
number
200 on success
​
data
array
Array of contact objects

​
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"

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