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

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

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

​
Body Parameters

​
phone_number
string
required
The phone number of the contact in international format (e.g., +12124567890)
​
full_name
string
required
The full name of the contact
​
country
string
The country of the contact
​
email
string
The email address of the contact
​
description
string
Optional description or notes about the contact
​
additional_data
array
Optional array of additional data fields for the contact

​
Response

​
status code
number
201 on successful creation
​
id
string
The unique identifier of the created 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
​
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 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"
  }'

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