Create Contact

# Create a contact with required fields
curl -X POST "https://api.contactship.ai/v1/contacts" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+12124567890",
    "full_name": "Juan Pérez"
  }'

# Create a contact with all available fields
curl -X POST "https://api.contactship.ai/v1/contacts" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    ]
  }'

// Using Fetch API to create a new contact
const createContact = async (contactData) => {
  try {
    const response = await fetch('https://api.contactship.ai/v1/contacts', {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(contactData)
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`HTTP error! Status: ${response.status}, Message: ${errorData.message || 'Unknown error'}`);
    }
    
    const newContact = await response.json();
    console.log('Contact created:', newContact);
    return newContact;
  } catch (error) {
    console.error('Error creating contact:', error);
  }
};

// Example usage
const contactData = {
  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'
    }
  ]
};

createContact(contactData);

import requests
import json

# Replace with your actual API key
api_key = "your-api-key"

# Base URL for the API
base_url = "https://api.contactship.ai"

# Headers
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

# Contact data
contact_data = {
    "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"
        }
    ]
}

# Make the POST request
response = requests.post(
    f"{base_url}/v1/contacts", 
    headers=headers,
    data=json.dumps(contact_data)
)

# Check if the request was successful
if response.status_code == 201:
    new_contact = response.json()
    print(f"Contact created successfully with ID: {new_contact['id']}")
    print(f"Created at: {new_contact['created_at']}")
elif response.status_code == 409:
    print("Error: A contact with this phone number already exists")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

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

POST

contacts

# Create a contact with required fields
curl -X POST "https://api.contactship.ai/v1/contacts" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+12124567890",
    "full_name": "Juan Pérez"
  }'

# Create a contact with all available fields
curl -X POST "https://api.contactship.ai/v1/contacts" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    ]
  }'

// Using Fetch API to create a new contact
const createContact = async (contactData) => {
  try {
    const response = await fetch('https://api.contactship.ai/v1/contacts', {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(contactData)
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`HTTP error! Status: ${response.status}, Message: ${errorData.message || 'Unknown error'}`);
    }
    
    const newContact = await response.json();
    console.log('Contact created:', newContact);
    return newContact;
  } catch (error) {
    console.error('Error creating contact:', error);
  }
};

// Example usage
const contactData = {
  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'
    }
  ]
};

createContact(contactData);

import requests
import json

# Replace with your actual API key
api_key = "your-api-key"

# Base URL for the API
base_url = "https://api.contactship.ai"

# Headers
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

# Contact data
contact_data = {
    "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"
        }
    ]
}

# Make the POST request
response = requests.post(
    f"{base_url}/v1/contacts", 
    headers=headers,
    data=json.dumps(contact_data)
)

# Check if the request was successful
if response.status_code == 201:
    new_contact = response.json()
    print(f"Contact created successfully with ID: {new_contact['id']}")
    print(f"Created at: {new_contact['created_at']}")
elif response.status_code == 409:
    print("Error: A contact with this phone number already exists")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

{
  "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 create a new contact in your organization’s database. You can provide various details about the contact including their name, phone number, email, and additional custom data fields.

Use Cases

Add a new lead or prospect to your CRM
Import contacts from external sources
Register new users or customers
Create contact records from form submissions

Headers

string

requerido

Your API key for authentication. You can find this in your dashboard under API settings.

Body Parameters

string

requerido

The phone number of the contact in international format (e.g., +12124567890)

string

requerido

The full name of the contact

string

The country of the contact

string

The email address of the contact

string

Optional description or notes about the contact

array

Optional array of additional data fields for the contact

Mostrar additional_data object

string

requerido

The type of the data field (e.g., “text”, “date”, “number”, “location”)

string

requerido

The name of the data field

string

requerido

The value of the data field

Response

number

201 on successful creation

string

The unique identifier of the created contact (UUID format)

string

The timestamp when the contact was created (ISO 8601 format)

string

The phone number of the contact

string

The full name of the contact

string

The country of the contact

string

The email of the contact

string

Description or notes about the contact

array

Additional data associated with the contact

string

The ID of the organization the contact belongs to

Error Codes

400 Bad Request - Invalid input data (e.g., missing required fields)
401 Unauthorized - Invalid or missing API key
409 Conflict - Contact with the same phone number already exists
500 Internal Server Error - Server-side error

Code Examples

# Create a contact with required fields
curl -X POST "https://api.contactship.ai/v1/contacts" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+12124567890",
    "full_name": "Juan Pérez"
  }'

# Create a contact with all available fields
curl -X POST "https://api.contactship.ai/v1/contacts" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    ]
  }'

// Using Fetch API to create a new contact
const createContact = async (contactData) => {
  try {
    const response = await fetch('https://api.contactship.ai/v1/contacts', {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(contactData)
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`HTTP error! Status: ${response.status}, Message: ${errorData.message || 'Unknown error'}`);
    }
    
    const newContact = await response.json();
    console.log('Contact created:', newContact);
    return newContact;
  } catch (error) {
    console.error('Error creating contact:', error);
  }
};

// Example usage
const contactData = {
  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'
    }
  ]
};

createContact(contactData);

import requests
import json

# Replace with your actual API key
api_key = "your-api-key"

# Base URL for the API
base_url = "https://api.contactship.ai"

# Headers
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

# Contact data
contact_data = {
    "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"
        }
    ]
}

# Make the POST request
response = requests.post(
    f"{base_url}/v1/contacts", 
    headers=headers,
    data=json.dumps(contact_data)
)

# Check if the request was successful
if response.status_code == 201:
    new_contact = response.json()
    print(f"Contact created successfully with ID: {new_contact['id']}")
    print(f"Created at: {new_contact['created_at']}")
elif response.status_code == 409:
    print("Error: A contact with this phone number already exists")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

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

Always use international format for phone numbers (e.g., +12124567890) to ensure consistency
Store the returned contact ID for future reference and updates
Validate data on your end before submitting to avoid 400 errors
Consider implementing deduplication checks before creating new contacts to avoid conflicts
Use meaningful and consistent naming conventions for additional_data fields to maintain data quality

Documentación API

Voz

WhatsApp (WABA)

Canales y Conversaciones

Organización

Agentes

Contactos

Etiquetas

Llamadas

Números de Teléfono

Use Cases

Headers

Body Parameters

Response

Error Codes

Code Examples

Notes and Best Practices

​Use Cases

​Headers

​Body Parameters

​Response

​Error Codes

​Code Examples

​Notes and Best Practices

Use Cases

Headers

Body Parameters

Response

Error Codes

Code Examples

Notes and Best Practices