Create Contact

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

​

Body Parameters

​

Response

​

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