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
Your API key for authentication. You can find this in your dashboard under API settings.
Query Parameters Filter contacts by full name (partial match). For example, using “John” will return all contacts with “John” in their name.
Filter contacts by email address (partial match). For example, using “gmail” will return all contacts with Gmail addresses.
Filter contacts by phone number (partial match). For example, using “+1212” will return contacts with phone numbers starting with +1212.
Response Array of contact objects The unique identifier of the contact (UUID format)
The timestamp when the contact was created (ISO 8601 format)
The phone number of the contact in international format (e.g., +12124567890)
The full name of the contact
The country of the contact
Description or notes about the contact
Additional data associated with the contact, each as a key-value pair with a type
The ID of the organization the contact belongs to
Error Codes
400 Bad Request - Invalid request parameters401 Unauthorized - Invalid or missing API key500 Internal Server Error - Server-side error
Code Examples cURL Example (All Contacts)
cURL Example (Filtered by name)
cURL Example (Multiple filters)
JavaScript Example
Python Example
# 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
