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

# Create Contact

> Create a new contact and associate them with a campaign.

Creates a new contact and enrolls them in the specified campaign. If a contact with the same phone number was previously deleted, they will be reactivated. If a contact already exists and is active, this request will update their information.

## Request Body

<ParamField body="phoneNumber" type="string" required>
  Phone number in E.164 format (e.g., `+11234567890`).
</ParamField>

<ParamField body="campaignId" type="string (UUID)" required>
  The ID of the campaign to associate this contact with. Use [List Campaigns](/api-reference/campaigns/list) to retrieve valid IDs.
</ParamField>

<ParamField body="name" type="string">
  Full name of the contact. Maximum 255 characters.
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone string (e.g., `America/New_York`). If omitted, the timezone is auto-detected from the phone number's area code.
</ParamField>

<ParamField body="customVariables" type="object">
  Key-value pairs of custom data to store on the contact.

  <Note>
    For campaigns with appointment scheduling enabled, `customVariables.email` is **required**.
  </Note>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true` on a successful request.
</ResponseField>

<ResponseField name="data" type="object">
  The created or updated contact object.

  <Expandable title="Contact fields">
    <ResponseField name="id" type="string (UUID)">
      Unique identifier for the contact.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string">
      Phone number in E.164 format.
    </ResponseField>

    <ResponseField name="name" type="string">
      Contact name.
    </ResponseField>

    <ResponseField name="campaignId" type="string (UUID)">
      Associated campaign ID.
    </ResponseField>

    <ResponseField name="customVariables" type="object">
      Custom key-value data stored on the contact.
    </ResponseField>

    <ResponseField name="timezone" type="string">
      IANA timezone string.
    </ResponseField>

    <ResponseField name="status" type="string">
      Contact status. Newly created contacts start as `active`.
    </ResponseField>

    <ResponseField name="createdAt" type="string (ISO 8601)">
      Timestamp of when the contact was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.guayaba.ai/contacts \
    -H "Content-Type: application/json" \
    -H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
    -d '{
      "phoneNumber": "+11234567890",
      "campaignId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Doe",
      "customVariables": {
        "email": "john@example.com",
        "company": "Acme Inc"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.guayaba.ai/contacts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
    },
    body: JSON.stringify({
      phoneNumber: '+11234567890',
      campaignId: '550e8400-e29b-41d4-a716-446655440000',
      name: 'John Doe',
      customVariables: {
        email: 'john@example.com',
        company: 'Acme Inc'
      }
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.guayaba.ai/contacts',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
      },
      json={
          'phoneNumber': '+11234567890',
          'campaignId': '550e8400-e29b-41d4-a716-446655440000',
          'name': 'John Doe',
          'customVariables': {
              'email': 'john@example.com',
              'company': 'Acme Inc'
          }
      }
  )

  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "success": true,
    "data": {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "phoneNumber": "+11234567890",
      "name": "John Doe",
      "campaignId": "550e8400-e29b-41d4-a716-446655440000",
      "customVariables": {
        "email": "john@example.com",
        "company": "Acme Inc"
      },
      "timezone": "America/New_York",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Validation error",
    "message": "phoneNumber is required and must be in E.164 format"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Not found",
    "message": "Campaign not found"
  }
  ```
</ResponseExample>