> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Contact

> Add a new contact to your organization

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

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication. You can find this in your dashboard under API settings.
</ParamField>

## Body Parameters

<ParamField body="phone_number" type="string" required>
  The phone number of the contact in international format (e.g., +12124567890)
</ParamField>

<ParamField body="full_name" type="string" required>
  The full name of the contact
</ParamField>

<ParamField body="country" type="string">
  The country of the contact
</ParamField>

<ParamField body="email" type="string">
  The email address of the contact
</ParamField>

<ParamField body="description" type="string">
  Optional description or notes about the contact
</ParamField>

<ParamField body="additional_data" type="array">
  Optional array of additional data fields for the contact

  <Expandable title="additional_data object">
    <ParamField body="type" type="string" required>
      The type of the data field (e.g., "text", "date", "number", "location")
    </ParamField>

    <ParamField body="field" type="string" required>
      The name of the data field
    </ParamField>

    <ParamField body="value" type="string" required>
      The value of the data field
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="status code" type="number">
  201 on successful creation
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier of the created contact (UUID format)
</ResponseField>

<ResponseField name="created_at" type="string">
  The timestamp when the contact was created (ISO 8601 format)
</ResponseField>

<ResponseField name="phone_number" type="string">
  The phone number of the contact
</ResponseField>

<ResponseField name="full_name" type="string">
  The full name of the contact
</ResponseField>

<ResponseField name="country" type="string">
  The country of the contact
</ResponseField>

<ResponseField name="email" type="string">
  The email of the contact
</ResponseField>

<ResponseField name="description" type="string">
  Description or notes about the contact
</ResponseField>

<ResponseField name="additional_data" type="array">
  Additional data associated with the contact
</ResponseField>

<ResponseField name="organization_id" type="string">
  The ID of the organization the contact belongs to
</ResponseField>

## 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

<RequestExample>
  ```bash cURL Example (Basic) theme={null}
  # 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"
    }'
  ```

  ```bash cURL Example (Complete) theme={null}
  # 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"
        }
      ]
    }'
  ```

  ```javascript JavaScript Example theme={null}
  // 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);
  ```

  ```python Python Example theme={null}
  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)
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## 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