API Integration Documentation

Use this API endpoint to programmatically add contacts to your contact list from your backend application.

Generate your API key from Settings > API section. For security, whitelist your backend system's IP address. Include the API key in the Authorization header of your requests.

POST/external/contact-list/v1/:listId/add

Add Contacts to List

This endpoint allows you to add one or more contacts to a specific contact list. You must provide an array of contact objects, where each contact contains their information.

API Endpoint

POST https://api.oblic.app/external/contact-list/v1/{listId}/add

Replace {listId} with your actual contact list ID (e.g., a459be9e-e6e5-11f0-967f-0af3f8fe5ae7).

Request Headers

பெயர்
Content-Type
வகை
string
விளக்கம்
Must be set to application/json
பெயர்
Authorization
வகை
string
விளக்கம்
Bearer token with your API key: Bearer YOUR_API_KEY

Request Body

The request body must be an array of contact objects. Each contact object has the following properties:

பெயர்
name
வகை
string
விளக்கம்
Contact's full name or display name
பெயர்
email
வகை
string
விளக்கம்
Valid email address
பெயர்
phone
வகை
string
விளக்கம்
Phone number with country code (without + sign, e.g., 911234567890)
பெயர்
whatsApp
வகை
string
விளக்கம்
WhatsApp number with country code (without + sign, e.g., 911234567890)

Request

POST

/external/contact-list/v1/:listId/add

curl -X POST 'https://api.oblic.app/external/contact-list/v1/a459be9e-e6e5-11f0-967f-0af3f8fe5ae7/add' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '[
    {
      "name": "John Doe",
      "email": "user@example.com",
      "phone": "911234567890",
      "whatsApp": "911234567890"
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "919876543210",
      "whatsApp": "919876543210"
    }
  ]'

Success Response (200)

{
  "status": "success",
  "data": null,
  "errors": null
}

Error Response (400/401/500)

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "cd": "INVALID_EMAIL",
      "message": "Invalid email address provided"
    }
  ]
}

Field Descriptions

Below is a detailed description of each field in the contact object:

பெயர்
name
வகை
string
விளக்கம்
Contact's full name or display name
This is the primary identifier for the contact in your list.
பெயர்
email
வகை
string
விளக்கம்
Valid email address
Must be a properly formatted email address. This field is required for all contacts.
பெயர்
phone
வகை
string
விளக்கம்
Phone number with country code
Optional field. Include the country code without the + sign (e.g., 911234567890 for India).
பெயர்
whatsApp
வகை
string
விளக்கம்
WhatsApp number with country code
Optional field. Include the country code without the + sign (e.g., 911234567890). This enables WhatsApp messaging capabilities for the contact.

Response Format

The API returns a consistent response format for both successful and failed requests.

Success Response

When contacts are successfully added, you'll receive a 200 status code with:

பெயர்
status
வகை
string
விளக்கம்
Will be "success" for successful operations
பெயர்
data
வகை
null
விளக்கம்
Will be null for this endpoint
பெயர்
errors
வகை
null
விளக்கம்
Will be null when there are no errors

Error Response

When an error occurs (status codes 400, 401, or 500), you'll receive:

பெயர்
status
வகை
string
விளக்கம்
Will be "error" for failed operations
பெயர்
data
வகை
null
விளக்கம்
Will be null when an error occurs
பெயர்
errors
வகை
array
விளக்கம்
An array of error objects, each containing a cd (error code) and message field

Success Example

{
  "status": "success",
  "data": null,
  "errors": null
}

Error Example

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "cd": "INVALID_EMAIL",
      "message": "Invalid email address provided"
    }
  ]
}

Best Practices

✓ Use Batch Operations

Since the API accepts an array of contacts, you can add multiple contacts in a single request to reduce API calls and improve performance.

✓ Validate Data Before Sending

Always validate email addresses and phone numbers in your application before making API requests to avoid unnecessary errors.

✓ Secure Your API Key

Never expose your API key in client-side code. Always make API calls from your backend server and whitelist your server's IP address.

✓ Handle Errors Gracefully

Implement proper error handling in your application to manage failed requests and provide meaningful feedback to users.