GET
/
v1
/
contacts
/
{identifier}
# Retrieve a contact using its ID
curl -X GET "https://api.contactship.ai/v1/contacts/c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6" \
  -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"
}
This endpoint allows you to retrieve a specific contact using different types of identifiers such as ID, phone number, or email address. This flexibility makes it easier to find contacts when you don’t have their unique ID.

​
Use Cases

  • Find a contact using their phone number when you don’t have their ID
  • Look up a contact by their email address
  • Verify if a contact already exists in your system
  • Retrieve contact details before making a call or sending a message

​
Path Parameters

​
identifier
string
required
The contact identifier, which can be an ID, phone number, or email address. For phone numbers, use international format (e.g., +12124567890).

​
Query Parameters

​
identifierType
string
Specifies what type of identifier is being used. Possible values:
  • id (default): Use when the identifier is the contact’s unique ID
  • phone_number: Use when the identifier is a phone number
  • email: Use when the identifier is an email address

​
Headers

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

​
Response

​
status code
number
200 on success
​
id
string
The unique identifier of the contact (UUID format)
​
created_at
string
The timestamp when the contact was created (ISO 8601 format)
​
phone_number
string
The phone number of the contact in international format (e.g., +12124567890)
​
full_name
string
The full name of the contact
​
country
string
The country of the contact
​
email
string
The email of the contact
​
description
string
Description or notes about the contact
​
additional_data
array
Additional data associated with the contact
​
organization_id
string
The ID of the organization the contact belongs to

​
Error Codes

  • 400 Bad Request - Invalid identifier format
  • 401 Unauthorized - Invalid or missing API key
  • 404 Not Found - Contact not found
  • 500 Internal Server Error - Server-side error

​
Code Examples

# Retrieve a contact using its ID
curl -X GET "https://api.contactship.ai/v1/contacts/c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6" \
  -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"
}

​
Notes and Best Practices

  • When using phone numbers as identifiers, always use the international format (e.g., +12124567890)
  • Remember to URL-encode identifiers, especially email addresses and phone numbers with special characters
  • The ID lookup is generally faster than lookups by email or phone number
  • If you’re unsure whether a contact exists, use this endpoint to check before creating a new contact
  • Consider implementing caching mechanisms for frequently accessed contacts