# 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
Your API key for authentication. You can find this in your dashboard under API settings.
Body Parameters
Response
The response is{ "statusCode": number, "data": object }. The fields below describe data.
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
