Skip to main content
GET
https://api.contactship.ai
/
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": "[email protected]",
    "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": "[email protected]",
    "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

​
x-api-key
string
required
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": "[email protected]",
    "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": "[email protected]",
    "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