Create Contact - Botista API Documentation

Overview

This endpoint allows you to create new contacts in a specific contact list. Contacts can include basic information like name, phone number, and email, as well as custom variant fields for additional data.

Path Parameters

contactList

string

required

The ID or identifier of the contact list where the contact will be created

Use Cases

Form Submissions: Add contacts from website forms
E-commerce Integrations: Create contacts from order data
CRM Sync: Synchronize contacts from external systems
Lead Capture: Store leads from marketing campaigns

Custom Variants

Variants allow you to store custom fields specific to your contact list. Each variant must be predefined in your contact list configuration.

Contact your administrator to set up custom variant fields for your contact list before using them in API requests.

Example Usage

cURL Example

curl -X POST https://api.botista.com/api/v1/external/contact-lists/123/create-contact \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": "+1234567890",
      "email": "john.doe@example.com"
    },
    "variants": [
      {
        "slug": "company",
        "value": "Acme Corp"
      },
      {
        "slug": "source",
        "value": "website"
      }
    ]
  }'

JavaScript Example

const createContact = async (contactListId, contactData) => {
  const response = await fetch(
    `https://api.botista.com/api/v1/external/contact-lists/${contactListId}/create-contact`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        data: {
          first_name: contactData.firstName,
          last_name: contactData.lastName,
          phone_number: contactData.phone,
          email: contactData.email
        },
        variants: contactData.customFields || []
      })
    }
  );

  return await response.json();
};

// Usage
const result = await createContact('123', {
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1234567890',
  email: 'john.doe@example.com',
  customFields: [
    { slug: 'company', value: 'Acme Corp' },
    { slug: 'source', value: 'website' }
  ]
});

PHP Example

use Illuminate\Support\Facades\Http;

$contactListId = '123';

$response = Http::post(
    "https://api.botista.com/api/v1/external/contact-lists/{$contactListId}/create-contact",
    [
        'data' => [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'phone_number' => '+1234567890',
            'email' => 'john.doe@example.com',
        ],
        'variants' => [
            [
                'slug' => 'company',
                'value' => 'Acme Corp',
            ],
            [
                'slug' => 'source',
                'value' => 'website',
            ],
        ],
    ]
);

$contact = $response->json();

Python Example

import requests

contact_list_id = "123"
url = f"https://api.botista.com/api/v1/external/contact-lists/{contact_list_id}/create-contact"

payload = {
    "data": {
        "first_name": "John",
        "last_name": "Doe",
        "phone_number": "+1234567890",
        "email": "john.doe@example.com"
    },
    "variants": [
        {
            "slug": "company",
            "value": "Acme Corp"
        },
        {
            "slug": "source",
            "value": "website"
        }
    ]
}

response = requests.post(url, json=payload)
contact = response.json()

Response Examples

Successful Creation

{
  "success": true,
  "message": "Contact created successfully",
  "data": {
    "id": "abc123xyz",
    "name": "John Doe",
    "phone_number": "+1234567890",
    "email": "john.doe@example.com",
    "gender": null
  }
}

Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "data.first_name": ["The first name field is required."],
    "data.phone_number": ["The phone number field is required."]
  }
}

Creation Failed

{
  "success": false,
  "message": "Failed to create contact",
  "error": "Contact with this phone number already exists in the list"
}

Validation Rules

data.first_name

string

required

Maximum 50 characters

data.last_name

string

Maximum 50 characters (optional)

data.phone_number

string

required

Maximum 20 characters

data.email

string

Must be a valid email format (optional)

variants

array

Array of custom variant objects (optional)

variants[].slug

string

required

Maximum 150 characters. Must exist in contact list variants. Each slug must be unique in the request.

variants[].value

string

Value for the variant field (optional, can be null)

Common Issues

Contact list not found

Verify that the contactList ID in the URL is correct and that the contact list exists in your account.

Invalid variant slug

The variant slug must be predefined in your contact list configuration. Check your contact list settings or contact your administrator.

Duplicate contact

If your contact list has duplicate prevention enabled, you may receive an error when trying to create a contact with an existing phone number or email.

Phone number format

While the API accepts various phone number formats, it’s recommended to use international format (e.g., +1234567890) for better compatibility.

Best Practices

Validate Input

Validate contact data on your end before sending to reduce API errors

Handle Errors

Implement proper error handling for validation and creation failures

Use Variants Wisely

Only include variants that are configured in your contact list

Rate Limiting

Implement exponential backoff if you’re creating contacts in bulk

Path Parameters

contactList

string

required

The ID or identifier of the contact list

Body

application/json

data

object

required

Show child attributes

variants

object[]

Custom variant fields for the contact (optional)

Show child attributes

Response

Contact created successfully

success

boolean

Example:

true

message

string

Example:

"Contact created successfully"

data

object

Show child attributes

Getting Started

Contacts

Documentation Index

​Overview

​Path Parameters

​Use Cases

​Custom Variants

​Example Usage

​cURL Example

​JavaScript Example

​PHP Example

​Python Example

​Response Examples

​Successful Creation

​Validation Error

​Creation Failed

​Validation Rules

​Common Issues

​Best Practices

Validate Input

Handle Errors

Use Variants Wisely

Rate Limiting

Path Parameters

Body

Response

Overview

Path Parameters

Use Cases

Custom Variants

Example Usage

cURL Example

JavaScript Example

PHP Example

Python Example

Response Examples

Successful Creation

Validation Error

Creation Failed

Validation Rules

Common Issues

Best Practices