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

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