# 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",
"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 { data: 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',
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",
"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()["data"]
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)
{
"statusCode": 201,
"data": {
"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"
}
}
Contactos
Create Contact
Add a new contact to your organization
POST
/
v1
/
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",
"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 { data: 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',
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",
"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()["data"]
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)
{
"statusCode": 201,
"data": {
"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
requerido
The country of the contact
string
The email address of the contact
array
Response
The response is{ "statusCode": number, "data": object }. The fields below describe data.
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 key409 Conflict- Contact with the same phone number already exists500 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",
"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 { data: 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',
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",
"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()["data"]
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)
{
"statusCode": 201,
"data": {
"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
